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 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 prompt_studio.prompt_studio_registry_v2.constants import (
JsonSchemaKey,
PromptStudioRegistryKeys,
)
from prompt_studio.prompt_studio_registry_v2.prompt_studio_registry_helper import (
PromptStudioRegistryHelper,
)
from rest_framework.serializers import ListField, Serializer, UUIDField, ValidationError
from workflow_manager.workflow_v2.constants import WorkflowKey
from workflow_manager.workflow_v2.models.workflow import Workflow
from backend.constants import RequestKey
from backend.serializers import AuditSerializer
from tool_instance_v2.constants import ToolInstanceKey as TIKey
from tool_instance_v2.constants import ToolKey
from tool_instance_v2.exceptions import ToolDoesNotExist
from tool_instance_v2.models import ToolInstance
from tool_instance_v2.tool_instance_helper import ToolInstanceHelper
from tool_instance_v2.tool_processor import ToolProcessor
from unstract.sdk1.adapters.enums import AdapterTypes
from unstract.tool_registry.dto import Tool
from unstract.tool_registry.tool_utils import ToolUtils
logger = logging.getLogger(__name__)
class ToolInstanceSerializer(AuditSerializer):
workflow_id = UUIDField(write_only=True)
class Meta:
model = ToolInstance
fields = "__all__"
extra_kwargs = {
TIKey.WORKFLOW: {
"required": False,
},
TIKey.VERSION: {
"required": False,
},
TIKey.METADATA: {
"required": False,
},
TIKey.STEP: {
"required": False,
},
}
def validate_workflow(self, value):
"""Refuse reparenting: the gate authorises against the stored parent."""
if self.instance and value != self.instance.workflow:
raise ValidationError("A tool cannot be moved to another workflow.")
return value
def validate_workflow_id(self, value):
"""Same guard for the declared alias -- ``workflow_id`` is the FK's
attname, so DRF writes the column through it directly.
"""
if self.instance and str(value) != str(self.instance.workflow_id):
raise ValidationError("A tool cannot be moved to another workflow.")
return value
def to_representation(self, instance: ToolInstance) -> dict[str, str]:
rep: dict[str, Any] = super().to_representation(instance)
tool_function = rep.get(TIKey.TOOL_ID)
if tool_function is None:
raise ToolDoesNotExist()
try:
tool: Tool = ToolProcessor.get_tool_by_uid(tool_function)
except ToolDoesNotExist:
return rep
rep[ToolKey.ICON] = tool.icon
rep[ToolKey.NAME] = tool.properties.display_name
# Transform adapter IDs back to names for UI display
metadata = rep.get(TIKey.METADATA, {})
if metadata:
rep[TIKey.METADATA] = self._transform_adapter_ids_to_names_for_display(
metadata, tool_function
)
return rep
def _transform_adapter_ids_to_names_for_display(
self, metadata: dict[str, Any], tool_uid: str
) -> dict[str, Any]:
"""Transform adapter IDs back to names for UI display."""
# Create a copy to avoid mutating the original metadata
display_metadata = metadata.copy()
try:
tool: Tool = ToolProcessor.get_tool_by_uid(tool_uid=tool_uid)
schema = ToolUtils.get_json_schema_for_tool(tool)
# Create mapping of adapter keys to their types
adapter_key_to_type = {}
for key in schema.get_llm_adapter_properties().keys():
adapter_key_to_type[key] = AdapterTypes.LLM
for key in schema.get_embedding_adapter_properties().keys():
adapter_key_to_type[key] = AdapterTypes.EMBEDDING
for key in schema.get_vector_db_adapter_properties().keys():
adapter_key_to_type[key] = AdapterTypes.VECTOR_DB
for key in schema.get_text_extractor_adapter_properties().keys():
adapter_key_to_type[key] = AdapterTypes.X2TEXT
for key in schema.get_ocr_adapter_properties().keys():
adapter_key_to_type[key] = AdapterTypes.OCR
# Transform IDs back to names for display
for adapter_key, adapter_type in adapter_key_to_type.items():
adapter_value = display_metadata.get(adapter_key)
if not adapter_value:
continue
# If it's a UUID (adapter ID), convert to name for display
if ToolInstanceHelper.is_uuid_format(adapter_value):
try:
adapter_name = AdapterInstance.objects.get(
id=adapter_value
).adapter_name
if adapter_name:
display_metadata[adapter_key] = adapter_name
else:
# Adapter ID exists but returns None - mark as orphaned
display_metadata[adapter_key] = (
f"[DELETED ADAPTER: {adapter_value}...]"
)
logger.warning(
f"Adapter ID {adapter_value} references a deleted or inaccessible adapter"
)
except Exception as e:
# If conversion fails, show user-friendly error
display_metadata[adapter_key] = f"[{adapter_value}...] NOT FOUND"
logger.error(
f"Could not resolve adapter ID {adapter_value} to name: {e}"
)
# If it's not a UUID, validate if the adapter name still exists
elif adapter_value and not ToolInstanceHelper.is_uuid_format(
adapter_value
):
try:
# Validate if adapter name still exists
adapter = AdapterProcessor.get_adapter_by_name_and_type(
adapter_type=adapter_type, adapter_name=adapter_value
)
if adapter:
# Adapter name is valid, display as-is
display_metadata[adapter_key] = adapter_value
else:
# Adapter name no longer exists (likely renamed)
display_metadata[adapter_key] = (
f"{adapter_value} [NEEDS UPDATE]"
)
logger.warning(
f"Adapter name '{adapter_value}' no longer exists for type {adapter_type} - may have been renamed"
)
except Exception as e:
# If validation fails, show error
display_metadata[adapter_key] = f"[{adapter_value} NOT FOUND]"
logger.error(
f"Could not validate adapter name '{adapter_value}': {e}"
)
except Exception as e:
logger.error(f"Error transforming adapter IDs to names: {e}", exc_info=True)
return display_metadata
@staticmethod
def _overlay_resolved_challenge_llm(
tool: Tool,
tool_settings: dict[str, Any],
tool_uid: str,
user: User | None,
) -> None:
"""Seed `challenge_llm` from the value the export already resolved.
`get_default_settings` walks the spec, and an adapter-valued property
with no `default` is seeded "". `challenge_llm` has none, so the
instance would store "" - and because the property declares
`adapterType: "LLM"`, an enum of real adapter IDs is injected into the
tool-instance schema, which "" then fails at deployment validation.
The export resolved a real adapter ID for this setting (falling back to
the default profile's LLM when the project set none), so prefer it.
Only seed a value this user can actually use. The enum injected at
deployment is built per-user, and an exported tool can be shared, so the
exporter's adapter may be invisible to whoever creates the instance -
and it may since have been deleted. Seeding such an id would trade the
"" enum violation for an equally opaque one naming a real UUID. Leaving
the key empty instead lets `update_metadata_with_default_adapter` fill
in this user's default LLM, which is what happened before the export
value was available at all.
Deliberately scoped to `challenge_llm` alone. The export's
`tool_settings` overlaps the spec on four other keys
(`enable_challenge`, `summarize_as_source`, `enable_highlight`,
`enable_word_confidence`); overlaying those would change whether
challenge, summarization and highlighting actually *run* on new
instances - a cost-, latency- and output-affecting change, and a
separate decision from fixing this validation failure.
Tools whose spec has no `challenge_llm` return before any query; a
Prompt-Studio-shaped tool with no registry row resolves to {}.
"""
challenge_llm_key = JsonSchemaKey.CHALLENGE_LLM
if challenge_llm_key not in tool_settings:
return
resolved_settings = PromptStudioRegistryHelper.get_resolved_settings(
prompt_registry_id=tool_uid
)
resolved_challenge_llm = resolved_settings.get(challenge_llm_key)
if not resolved_challenge_llm:
logger.debug(
"Export for tool %s resolved no challenge_llm; leaving the "
"spec-seeded default in place",
tool_uid,
)
return
if not ToolInstanceSerializer._is_adapter_usable_by(resolved_challenge_llm, user):
logger.warning(
"Resolved challenge_llm %s for tool %s is not accessible to the "
"creating user; falling back to their default LLM adapter",
resolved_challenge_llm,
tool_uid,
)
return
tool_settings[challenge_llm_key] = resolved_challenge_llm
# Write the companion ID key alongside, the shape every other writer
# emits (see `ToolInstanceHelper.update_metadata_with_default_adapter`).
adapter_property = tool.spec.properties.get(challenge_llm_key, {})
adapter_id_key = ToolInstanceHelper.get_adapter_id_key(adapter_property)
tool_settings[adapter_id_key] = resolved_challenge_llm
@staticmethod
def _is_adapter_usable_by(adapter_id: str, user: User | None) -> bool:
"""Whether `adapter_id` is an LLM adapter visible to `user`.
Mirrors `AdapterProcessor.get_adapters_by_type` exactly - same
`for_user` scoping, same `adapter_type` predicate - because that builds
the enum this value is validated against at deploy time, and any
divergence lets a value through here that the enum then rejects. The
type predicate is load-bearing: `CustomTool.challenge_llm` is an
unconstrained FK whose serializer has no `validate_challenge_llm`,
unlike its `summarize_llm_adapter` sibling, so a non-LLM adapter can
reach it.
Without a user there is no scope to check against, and answering "yes"
would seed on mere existence - passing another user's private adapter.
Refuse instead: the caller then leaves the key empty and the default
adapter fills it, which is safe in every case. Unreachable today, since
every site that constructs this serializer to write goes through
`get_serializer`, which supplies the request.
"""
if user is None:
return False
return (
AdapterInstance.objects.for_user(user)
.filter(id=adapter_id, adapter_type=AdapterTypes.LLM.value)
.exists()
)
def create(self, validated_data: dict[str, Any]) -> Any:
workflow_id = validated_data.pop(WorkflowKey.WF_ID)
try:
workflow = Workflow.objects.get(pk=workflow_id)
except Workflow.DoesNotExist:
raise ValidationError(f"Workflow with ID {workflow_id} does not exist.")
validated_data[TIKey.WORKFLOW] = workflow
if workflow.tool_instances.count() > 0:
raise ValidationError(
f"Workflow with ID {workflow_id} can't have more than one tool."
)
tool_uid = validated_data.get(TIKey.TOOL_ID)
if not tool_uid:
raise ToolDoesNotExist()
tool: Tool = ToolProcessor.get_tool_by_uid(tool_uid=tool_uid)
# TODO: Handle other fields once tools SDK is out
validated_data[TIKey.PK] = uuid.uuid4()
# TODO: Use version from tool props
validated_data[TIKey.VERSION] = ""
tool_settings = ToolProcessor.get_default_settings(tool)
request = self.context.get(RequestKey.REQUEST)
self._overlay_resolved_challenge_llm(
tool,
tool_settings,
str(tool_uid),
getattr(request, "user", None),
)
validated_data[TIKey.METADATA] = {
# TODO: Review and remove tool instance ID
WorkflowKey.WF_TOOL_INSTANCE_ID: str(validated_data[TIKey.PK]),
PromptStudioRegistryKeys.PROMPT_REGISTRY_ID: str(tool_uid),
**tool_settings,
}
if TIKey.STEP not in validated_data:
validated_data[TIKey.STEP] = workflow.tool_instances.count() + 1
# Workflow will get activated on adding tools to workflow
if not workflow.is_active:
workflow.is_active = True
workflow.save()
return super().create(validated_data)
class ToolInstanceReorderSerializer(Serializer):
workflow_id = UUIDField()
tool_instances = ListField(child=UUIDField())
def validate(self, data: dict[str, Any]) -> dict[str, Any]:
workflow_id = data.get(WorkflowKey.WF_ID)
tool_instances = data.get(WorkflowKey.WF_TOOL_INSTANCES, [])
# Check if the workflow exists
try:
workflow = Workflow.objects.get(pk=workflow_id)
except Workflow.DoesNotExist:
raise ValidationError(f"Workflow with ID {workflow_id} does not exist.")
# Check if the number of tool instances matches the actual count
tool_instance_count = workflow.tool_instances.count()
if len(tool_instances) != tool_instance_count:
msg = (
f"Incorrect number of tool instances passed: "
f"{len(tool_instances)}, expected: {tool_instance_count}"
)
logger.error(msg)
raise ValidationError(detail=msg)
# Check if each tool instance exists in the workflow
existing_tool_instance_ids = workflow.tool_instances.values_list("id", flat=True)
for tool_instance_id in tool_instances:
if tool_instance_id not in existing_tool_instance_ids:
raise ValidationError(
"One or more tool instances do not exist in the workflow."
)
return data