LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
import logging
import os
import uuid
from typing import Any
from account_v2.models import User
from adapter_processor_v2.adapter_processor import AdapterProcessor
from adapter_processor_v2.models import AdapterInstance
from django.core.exceptions import PermissionDenied
from django.core.exceptions import ValidationError as DjangoValidationError
from jsonschema.exceptions import ValidationError as JSONValidationError
from permissions.permission import (
_is_resource_owner,
_is_resource_viewer,
has_group_access,
)
from prompt_studio.prompt_studio_registry_v2.models import PromptStudioRegistry
from tenant_account_v2.organization_member_service import OrganizationMemberService
from workflow_manager.workflow_v2.constants import WorkflowKey
from tool_instance_v2.constants import JsonSchemaKey
from tool_instance_v2.exceptions import ToolSettingValidationError
from tool_instance_v2.models import ToolInstance
from tool_instance_v2.tool_processor import ToolProcessor
from unstract.sdk1.constants import AdapterTypes
from unstract.sdk1.tool.validator import DefaultsGeneratingValidator
from unstract.tool_registry.constants import AdapterPropertyKey
from unstract.tool_registry.dto import Spec, Tool
from unstract.tool_registry.tool_utils import ToolUtils
# Import agentic registry if available (cloud-only feature)
try:
from pluggable_apps.agentic_studio_registry.models import AgenticStudioRegistry
IS_AGENTIC_REGISTRY_AVAILABLE = True
except ImportError:
IS_AGENTIC_REGISTRY_AVAILABLE = False
logger = logging.getLogger(__name__)
class ToolInstanceHelper:
@staticmethod
def get_tool_instances_by_workflow(
workflow_id: str,
order_by: str,
lookup: dict[str, Any] | None = None,
offset: int | None = None,
limit: int | None = None,
) -> list[ToolInstance]:
wf_filter = {}
if lookup:
wf_filter = lookup
wf_filter[WorkflowKey.WF_ID] = workflow_id
if limit:
offset_value = 0 if not offset else offset
to = offset_value + limit
return list(
ToolInstance.objects.filter(**wf_filter)[offset_value:to].order_by(
order_by
)
)
return list(ToolInstance.objects.filter(**wf_filter).all().order_by(order_by))
@staticmethod
def update_instance_metadata(
org_id: str, tool_instance: ToolInstance, metadata: dict[str, Any]
) -> None:
ToolInstanceHelper.update_metadata_with_adapter_instances(
metadata, tool_instance.tool_id
)
metadata[JsonSchemaKey.TENANT_ID] = org_id
tool_instance.metadata = metadata
tool_instance.save()
@staticmethod
def get_adapter_id_key(adapter_property: dict[str, Any]) -> str:
"""The metadata key holding a spec property's companion adapter ID.
Every writer stores an adapter key and this companion together; a
populated adapter key with a missing ID key bypasses the lazy migrator
and then fails schema enum validation. Resolved in one place so the
writers cannot drift on where that companion lives.
"""
return adapter_property.get(
AdapterPropertyKey.ADAPTER_ID_KEY, AdapterPropertyKey.ADAPTER_ID
)
@staticmethod
def update_metadata_with_adapter_properties(
metadata: dict[str, Any],
adapter_key: str,
adapter_property: dict[str, Any],
adapter_type: AdapterTypes,
) -> None:
"""Update the metadata dictionary with adapter properties.
Handles both legacy metadata (adapter names) and new metadata (adapter IDs).
Automatically converts adapter names to IDs for consistency.
Parameters:
metadata (dict[str, Any]):
The metadata dictionary to be updated with adapter properties.
adapter_key (str):
The key in the metadata dictionary corresponding to the adapter.
adapter_property (dict[str, Any]):
The properties of the adapter.
adapter_type (AdapterTypes):
The type of the adapter.
Returns:
None
"""
if adapter_key in metadata:
adapter_value = metadata[adapter_key]
if not adapter_value:
return
if ToolInstanceHelper.is_uuid_format(adapter_value):
logger.debug(f"Adapter value '{adapter_value}' is already in UUID format")
adapter = AdapterInstance.objects.get(
id=adapter_value, adapter_type=adapter_type.value
)
else:
adapter = AdapterProcessor.get_adapter_by_name_and_type(
adapter_type=adapter_type, adapter_name=adapter_value
)
adapter_id = str(adapter.id)
metadata_key_for_id = ToolInstanceHelper.get_adapter_id_key(adapter_property)
# Keep adapter_key and adapter_id_key both canonical to the resolved
# target UUID; otherwise stale UUID-shaped values at adapter_key
# bypass the lazy migrator and fail schema enum validation later.
metadata[adapter_key] = adapter_id
metadata[metadata_key_for_id] = adapter_id
@staticmethod
def update_metadata_with_adapter_instances(
metadata: dict[str, Any], tool_uid: str
) -> None:
"""Update the metadata dictionary with adapter instances.
Parameters:
metadata (dict[str, Any]):
The metadata dictionary to be updated with adapter instances.
Returns:
None
"""
tool: Tool = ToolProcessor.get_tool_by_uid(tool_uid=tool_uid)
schema: Spec = ToolUtils.get_json_schema_for_tool(tool)
llm_properties = schema.get_llm_adapter_properties()
embedding_properties = schema.get_embedding_adapter_properties()
vector_db_properties = schema.get_vector_db_adapter_properties()
x2text_properties = schema.get_text_extractor_adapter_properties()
ocr_properties = schema.get_ocr_adapter_properties()
for adapter_key, adapter_property in llm_properties.items():
ToolInstanceHelper.update_metadata_with_adapter_properties(
metadata=metadata,
adapter_key=adapter_key,
adapter_property=adapter_property,
adapter_type=AdapterTypes.LLM,
)
for adapter_key, adapter_property in embedding_properties.items():
ToolInstanceHelper.update_metadata_with_adapter_properties(
metadata=metadata,
adapter_key=adapter_key,
adapter_property=adapter_property,
adapter_type=AdapterTypes.EMBEDDING,
)
for adapter_key, adapter_property in vector_db_properties.items():
ToolInstanceHelper.update_metadata_with_adapter_properties(
metadata=metadata,
adapter_key=adapter_key,
adapter_property=adapter_property,
adapter_type=AdapterTypes.VECTOR_DB,
)
for adapter_key, adapter_property in x2text_properties.items():
ToolInstanceHelper.update_metadata_with_adapter_properties(
metadata=metadata,
adapter_key=adapter_key,
adapter_property=adapter_property,
adapter_type=AdapterTypes.X2TEXT,
)
for adapter_key, adapter_property in ocr_properties.items():
ToolInstanceHelper.update_metadata_with_adapter_properties(
metadata=metadata,
adapter_key=adapter_key,
adapter_property=adapter_property,
adapter_type=AdapterTypes.OCR,
)
@staticmethod
def update_metadata_with_default_adapter(
adapter_type: AdapterTypes,
schema_spec: Spec,
adapter: AdapterInstance,
metadata: dict[str, Any],
) -> None:
"""Update the metadata of a tool instance with default values for
enabled adapters.
Parameters:
adapter_type (AdapterTypes): The type of adapter to update
the metadata for.
schema_spec (Spec): The schema specification for the tool.
adapter (AdapterInstance): The adapter instance to use for updating
the metadata.
metadata (dict[str, Any]): The metadata dictionary to update.
Returns:
None
"""
properties = {}
if adapter_type == AdapterTypes.LLM:
properties = schema_spec.get_llm_adapter_properties()
if adapter_type == AdapterTypes.EMBEDDING:
properties = schema_spec.get_embedding_adapter_properties()
if adapter_type == AdapterTypes.VECTOR_DB:
properties = schema_spec.get_vector_db_adapter_properties()
if adapter_type == AdapterTypes.X2TEXT:
properties = schema_spec.get_text_extractor_adapter_properties()
if adapter_type == AdapterTypes.OCR:
properties = schema_spec.get_ocr_adapter_properties()
for adapter_key, adapter_property in properties.items():
metadata_key_for_id = ToolInstanceHelper.get_adapter_id_key(adapter_property)
# Only fill in what has no value yet. This runs right after tool
# instance creation, which may already have seeded a key with a
# value resolved for that specific tool - `challenge_llm` carries
# the exported project's challenger LLM, and it is one of the LLM
# adapter properties walked here. Overwriting it would replace a
# tool-specific choice with the user's global default.
existing_value = metadata.get(adapter_key)
if existing_value:
# Keep the pair consistent for whoever populated the adapter
# key. No caller reaching here today leaves the ID key unset -
# this holds the invariant rather than repairing a known writer.
# Cheap and worth keeping: a populated adapter key with a
# missing ID key bypasses the lazy migrator and then fails
# schema enum validation (see
# `update_metadata_with_adapter_properties`).
metadata.setdefault(metadata_key_for_id, existing_value)
continue
metadata[adapter_key] = str(adapter.id)
metadata[metadata_key_for_id] = str(adapter.id)
@staticmethod
def update_metadata_with_default_values(
tool_instance: ToolInstance, user: User
) -> None:
"""Update the metadata of a tool instance with default values for
enabled adapters.
Parameters:
tool_instance (ToolInstance): The tool instance to update the
metadata.
Returns:
None
"""
metadata: dict[str, Any] = tool_instance.metadata
tool_uuid = tool_instance.tool_id
tool: Tool = ToolProcessor.get_tool_by_uid(tool_uid=tool_uuid)
schema: Spec = ToolUtils.get_json_schema_for_tool(tool)
default_adapters = AdapterProcessor.get_default_adapters(user=user)
for adapter in default_adapters:
try:
adapter_type = AdapterTypes(adapter.adapter_type)
ToolInstanceHelper.update_metadata_with_default_adapter(
adapter_type=adapter_type,
schema_spec=schema,
adapter=adapter,
metadata=metadata,
)
except ValueError:
logger.warning(f"Invalid AdapterType {adapter.adapter_type}")
tool_instance.metadata = metadata
tool_instance.save()
@staticmethod
def get_relative_path(absolute_path: str, base_path: str) -> str:
if absolute_path.startswith(base_path):
relative_path = os.path.relpath(absolute_path, base_path)
else:
relative_path = absolute_path
if relative_path == ".":
relative_path = ""
return relative_path
@staticmethod
def reorder_tool_instances(
instances_to_reorder: list[uuid.UUID],
workflow_id: uuid.UUID | None = None,
) -> None:
"""Reorders tool instances based on the list of tool UUIDs received.
Saves the instance in the DB.
Args:
instances_to_reorder (list[uuid.UUID]): Desired order of tool UUIDs
workflow_id (uuid.UUID | None): When given, scope the lookup to
this workflow so a stray UUID can't reach a foreign row.
"""
logger.info("Reordering instances: %s", instances_to_reorder)
queryset = ToolInstance.objects
if workflow_id is not None:
queryset = queryset.filter(workflow_id=workflow_id)
for step, tool_instance_id in enumerate(instances_to_reorder):
tool_instance = queryset.get(pk=tool_instance_id)
tool_instance.step = step + 1
tool_instance.save()
@staticmethod
def is_uuid_format(value: str) -> bool:
"""Check if a string is in UUID format."""
if not value or not isinstance(value, str):
return False
try:
uuid.UUID(value)
return True
except ValueError:
return False
@staticmethod
def has_adapter_ids_in_metadata(metadata: dict[str, Any], tool_uid: str) -> bool:
"""Check if metadata already uses adapter IDs instead of names."""
tool: Tool = ToolProcessor.get_tool_by_uid(tool_uid=tool_uid)
schema: Spec = ToolUtils.get_json_schema_for_tool(tool)
# Get all adapter keys for this tool
adapter_keys = set()
adapter_keys.update(schema.get_llm_adapter_properties().keys())
adapter_keys.update(schema.get_embedding_adapter_properties().keys())
adapter_keys.update(schema.get_vector_db_adapter_properties().keys())
adapter_keys.update(schema.get_text_extractor_adapter_properties().keys())
adapter_keys.update(schema.get_ocr_adapter_properties().keys())
# Check if any adapter value is in UUID format (indicates already migrated)
for key in adapter_keys:
if (
key in metadata
and metadata[key]
and ToolInstanceHelper.is_uuid_format(metadata[key])
):
return True # Found at least one UUID, assume migrated
return False # No UUIDs found, still using names
@staticmethod
def _migrate_adapter_keys_for_type(
metadata: dict[str, Any],
adapter_keys: dict[str, Any],
adapter_type: AdapterTypes,
) -> tuple[dict[str, Any], bool]:
"""Helper method to migrate adapter names to IDs for a specific adapter type."""
needs_update = False
for adapter_key in adapter_keys.keys():
if (
adapter_key in metadata
and metadata[adapter_key]
and not ToolInstanceHelper.is_uuid_format(metadata[adapter_key])
):
adapter_name = metadata[adapter_key]
adapter = AdapterProcessor.get_adapter_by_name_and_type(
adapter_type=adapter_type, adapter_name=adapter_name
)
logger.info(
f"Migrating {adapter_type.value} adapter '{adapter_name}' to ID '{adapter.id}'"
)
metadata[adapter_key] = str(adapter.id)
needs_update = True
return metadata, needs_update
@staticmethod
def ensure_adapter_ids_in_metadata(
tool_instance: ToolInstance, user: User = None
) -> dict[str, Any]:
"""Lazy migration: convert adapter names to IDs if needed and update database."""
metadata = tool_instance.metadata.copy()
# Check if already migrated
if ToolInstanceHelper.has_adapter_ids_in_metadata(
metadata, tool_instance.tool_id
):
return metadata
logger.info(f"Performing lazy migration for tool instance {tool_instance.id}")
# Get tool schema and name for error messages
tool: Tool = ToolProcessor.get_tool_by_uid(tool_uid=tool_instance.tool_id)
schema: Spec = ToolUtils.get_json_schema_for_tool(tool)
overall_needs_update = False
# Migrate each adapter type
adapter_types_to_migrate = [
(schema.get_llm_adapter_properties(), AdapterTypes.LLM),
(schema.get_embedding_adapter_properties(), AdapterTypes.EMBEDDING),
(schema.get_vector_db_adapter_properties(), AdapterTypes.VECTOR_DB),
(schema.get_text_extractor_adapter_properties(), AdapterTypes.X2TEXT),
(schema.get_ocr_adapter_properties(), AdapterTypes.OCR),
]
for adapter_properties, adapter_type in adapter_types_to_migrate:
if adapter_properties: # Only process if this tool uses this adapter type
metadata, needs_update = (
ToolInstanceHelper._migrate_adapter_keys_for_type(
metadata=metadata,
adapter_keys=adapter_properties,
adapter_type=adapter_type,
)
)
overall_needs_update = overall_needs_update or needs_update
# Update database if changes were made
if overall_needs_update:
tool_instance.metadata = metadata
tool_instance.save()
logger.info(
f"Successfully migrated tool instance {tool_instance.id} to use adapter IDs"
)
return metadata
@staticmethod
def validate_tool_settings(
user: User, tool_uid: str, tool_meta: dict[str, Any]
) -> bool:
"""Function to validate Tools settings."""
# check if exported tool is valid for the user who created workflow
ToolInstanceHelper.validate_tool_access(user=user, tool_uid=tool_uid)
ToolInstanceHelper.validate_adapter_permissions(
user=user, tool_uid=tool_uid, tool_meta=tool_meta
)
tool: Tool = ToolProcessor.get_tool_by_uid(tool_uid=tool_uid)
tool_name: str = (
tool.properties.display_name if tool.properties.display_name else tool_uid
)
schema_json: dict[str, Any] = ToolProcessor.get_json_schema_for_tool(
tool_uid=tool_uid, user=user
)
try:
DefaultsGeneratingValidator(schema_json).validate(tool_meta)
except JSONValidationError as e:
logger.error(e, stack_info=True, exc_info=True)
err_msg = e.message
# TODO: Support other JSON validation errors or consider following
# https://github.com/networknt/json-schema-validator/blob/master/doc/cust-msg.md
if e.validator == "required":
for validator_val in e.validator_value:
required_prop = e.schema.get("properties").get(validator_val)
required_display_name = required_prop.get("title")
err_msg = err_msg.replace(validator_val, required_display_name)
elif e.validator == "minItems":
validated_entity_display_name = e.schema.get("title")
err_msg = (
f"'{validated_entity_display_name}' requires atleast"
f" {e.validator_value} values."
)
elif e.validator == "maxItems":
validated_entity_display_name = e.schema.get("title")
err_msg = (
f"'{validated_entity_display_name}' requires atmost"
f" {e.validator_value} values."
)
else:
logger.warning(f"Unformatted exception sent to user: {err_msg}")
raise ToolSettingValidationError(
f"Error validating tool settings for '{tool_name}': {err_msg}"
)
return True
@staticmethod
def validate_adapter_permissions(
user: User, tool_uid: str, tool_meta: dict[str, Any]
) -> None:
tool: Tool = ToolProcessor.get_tool_by_uid(tool_uid=tool_uid)
adapter_ids: set[str] = set()
for llm in tool.properties.adapter.language_models:
if llm.is_enabled and llm.adapter_id:
adapter_id = tool_meta[llm.adapter_id]
elif llm.is_enabled:
adapter_id = tool_meta[AdapterPropertyKey.DEFAULT_LLM_ADAPTER_ID]
adapter_ids.add(adapter_id)
for vdb in tool.properties.adapter.vector_stores:
if vdb.is_enabled and vdb.adapter_id:
adapter_id = tool_meta[vdb.adapter_id]
elif vdb.is_enabled:
adapter_id = tool_meta[AdapterPropertyKey.DEFAULT_VECTOR_DB_ADAPTER_ID]
adapter_ids.add(adapter_id)
for embedding in tool.properties.adapter.embedding_services:
if embedding.is_enabled and embedding.adapter_id:
adapter_id = tool_meta[embedding.adapter_id]
elif embedding.is_enabled:
adapter_id = tool_meta[AdapterPropertyKey.DEFAULT_EMBEDDING_ADAPTER_ID]
adapter_ids.add(adapter_id)
for text_extractor in tool.properties.adapter.text_extractors:
if text_extractor.is_enabled and text_extractor.adapter_id:
adapter_id = tool_meta[text_extractor.adapter_id]
elif text_extractor.is_enabled:
adapter_id = tool_meta[AdapterPropertyKey.DEFAULT_X2TEXT_ADAPTER_ID]
adapter_ids.add(adapter_id)
ToolInstanceHelper.validate_adapter_access(user=user, adapter_ids=adapter_ids)
@staticmethod
def validate_adapter_access(
user: User,
adapter_ids: set[str],
) -> None:
adapter_instances = AdapterInstance.objects.filter(id__in=adapter_ids).all()
is_admin = OrganizationMemberService.is_user_organization_admin(user)
# A platform key's service account is trusted across its own org, the
# same bypass every other access surface applies. Ownership no longer
# names it (UN-3853), so without this a key-provisioned workflow would
# fail its own execution.
is_service_account = getattr(user, "is_service_account", False)
for adapter_instance in adapter_instances:
if not adapter_instance.is_usable:
logger.error(
"Free usage for the configured sample adapter %s exhausted",
adapter_instance.id,
)
error_msg = "Permission Error: Free usage for the configured trial adapter exhausted.Please connect your own service accounts to continue.Please see our documentation for more details:https://docs.unstract.com/unstract_platform/setup_accounts/whats_needed" # noqa: E501
raise PermissionDenied(error_msg)
if not (
is_admin
or is_service_account
or adapter_instance.shared_to_org
or _is_resource_owner(user, adapter_instance)
or _is_resource_viewer(user, adapter_instance)
or has_group_access(user, adapter_instance)
):
logger.error(
"User %s doesn't have access to adapter %s",
user.user_id,
adapter_instance.id,
)
raise PermissionDenied(
"You don't have permission to perform this action."
)
@staticmethod
def validate_tool_access(
user: User,
tool_uid: str,
) -> None:
"""Validate user access to a tool (prompt studio or agentic studio).
Args:
user: User requesting access
tool_uid: Tool UID (could be prompt_registry_id or agentic_registry_id)
Raises:
PermissionDenied: If user doesn't have access to the tool
"""
# Try to find the tool in PromptStudioRegistry first
try:
if PromptStudioRegistry.objects.filter(pk=tool_uid).exists():
# Access derives from the linked project's current share
# state, not the export-time snapshot.
if (
PromptStudioRegistry.objects.list_tools(user)
.filter(pk=tool_uid)
.exists()
):
return
raise PermissionDenied(
"You don't have permission to perform this action."
)
except DjangoValidationError:
# Invalid UUID format, might be a static tool
logger.info(f"Not validating tool access for tool: {tool_uid}")
return
# Try to find the tool in AgenticStudioRegistry if available
if IS_AGENTIC_REGISTRY_AVAILABLE:
try:
if AgenticStudioRegistry.objects.filter(pk=tool_uid).exists():
# Access derives from the linked project's current share
# state, not the export-time snapshot.
if (
AgenticStudioRegistry.objects.list_tools(user)
.filter(pk=tool_uid)
.exists()
):
return
raise PermissionDenied(
"You don't have permission to perform this action."
)
except DjangoValidationError:
# Invalid UUID format, might be a static tool
logger.info(f"Not validating tool access for tool: {tool_uid}")
return
# If we reach here, it's likely a static tool from registry
# No validation needed for static tools
logger.info(f"Not validating tool access for tool: {tool_uid}")
return