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-3022 [FEAT] - Enable HITL rule engine for API deployments (#1703)
vishnuszipstackcba9ccb22d45
diff --git a/backend/plugins/workflow_manager/workflow_v2/utils.py b/backend/plugins/workflow_manager/workflow_v2/utils.pyindex b96034ec6..fa8a36bcb 100644--- a/backend/plugins/workflow_manager/workflow_v2/utils.py+++ b/backend/plugins/workflow_manager/workflow_v2/utils.py@@ -61,18 +61,44 @@ class WorkflowUtil:"""return file_hash+ @staticmethod+ def validate_rule_engine(+ result: Any | None,+ workflow: Workflow,+ file_destination: tuple[str, str] | None,+ rule_type: str = "DB",+ ) -> bool:+ """Placeholder method to check the rule engine - MRQ++ Args:+ result (Optional[Any]): The result dictionary containing+ confidence_data.+ workflow (Workflow): The workflow to retrieve the rules.+ file_destination (Optional[tuple[str, str]]): The destination of+ the file (e.g., MANUALREVIEW or other).+ rule_type (str): Rule type - "DB" for database destination,+ "API" for API deployments with hitl_queue_name.++ Returns:+ bool: True if the field_key conditions are met based on rule logic+ and file destination.+ """+ return False+@staticmethoddef validate_db_rule(result: Any | None,- workflow_id: Workflow,+ workflow: Workflow,file_destination: tuple[str, str] | None,) -> bool:- """Placeholder method to check the db rules - MRQ+ """Backward compatible method to check the db rules - MRQ++ Deprecated: Use validate_rule_engine instead.Args:result (Optional[Any]): The result dictionary containingconfidence_data.- workflow_id (str): The ID of the workflow to retrieve the rules.+ workflow (Workflow): The workflow to retrieve the rules.file_destination (Optional[tuple[str, str]]): The destination ofthe file (e.g., MANUALREVIEW or other).@@ -80,6 +106,21 @@ class WorkflowUtil:bool: True if the field_key conditions are met based on rule logicand file destination."""+ return WorkflowUtil.validate_rule_engine(+ result, workflow, file_destination, rule_type="DB"+ )++ @staticmethod+ def has_api_rules(workflow: Workflow) -> bool:+ """Check if API rules are configured for a workflow.++ Args:+ workflow (Workflow): The workflow to check.++ Returns:+ bool: True if API rules exist for this workflow, False otherwise.+ For OSS version, always returns False.+ """return False@staticmethoddiff --git a/backend/workflow_manager/endpoint_v2/destination.py b/backend/workflow_manager/endpoint_v2/destination.pyindex b47e0e66a..44e2ac853 100644--- a/backend/workflow_manager/endpoint_v2/destination.py+++ b/backend/workflow_manager/endpoint_v2/destination.py@@ -177,7 +177,15 @@ class DestinationConnector(BaseConnector):input_file_path: str,file_execution_id: str,) -> bool:- """Determines if HITL processing should be performed, returning True if data was pushed to the queue."""+ """Determines if HITL processing should be performed, returning True if data was pushed to the queue.++ The logic is:+ 1. packet_id takes precedence - always push to packet queue+ 2. hitl_queue_name with API rules:+ - If no API rules configured → Push ALL to HITL (backward compatible)+ - If API rules exist → Evaluate rules, push only if rules match+ 3. Database destination → Evaluate DB rules+ """# Check packet_id first - it takes precedence over hitl_queue_nameif self.packet_id:logger.info(@@ -191,26 +199,55 @@ class DestinationConnector(BaseConnector):)return True- # Check if API deployment requested HITL override+ # Check if API deployment requested HITL override with hitl_queue_nameif self.hitl_queue_name:- logger.info(f"API HITL override: pushing to queue for file {file_name}")- self._push_data_to_queue(- file_name=file_name,- workflow=workflow,- input_file_path=input_file_path,- file_execution_id=file_execution_id,- )- return True+ # Check if API rules are configured for this workflow+ if WorkflowUtil.has_api_rules(workflow):+ # API rules exist - evaluate them+ execution_result = self.get_tool_execution_result()+ if WorkflowUtil.validate_rule_engine(+ execution_result,+ workflow,+ file_hash.file_destination,+ rule_type="API",+ ):+ logger.info(+ f"API rules matched: pushing to queue for file {file_name}"+ )+ self._push_data_to_queue(+ file_name=file_name,+ workflow=workflow,+ input_file_path=input_file_path,+ file_execution_id=file_execution_id,+ )+ return True+ else:+ logger.info(+ f"API rules not matched: returning result for file {file_name}"+ )+ return False+ else:+ # No API rules configured - backward compatible behavior: push ALL to HITL+ logger.info(+ f"No API rules configured: pushing to queue for file {file_name}"+ )+ self._push_data_to_queue(+ file_name=file_name,+ workflow=workflow,+ input_file_path=input_file_path,+ file_execution_id=file_execution_id,+ )+ return True# Skip HITL validation if we're using file_history and no execution result is availableif self.is_api and self.use_file_history:return False- # Otherwise use existing workflow-based HITL logic+ # Otherwise use existing workflow-based HITL logic for DB destinationsexecution_result = self.get_tool_execution_result()- if WorkflowUtil.validate_db_rule(- execution_result, workflow, file_hash.file_destination+ if WorkflowUtil.validate_rule_engine(+ execution_result, workflow, file_hash.file_destination, rule_type="DB"):self._push_data_to_queue(file_name=file_name,@@ -934,6 +971,7 @@ class DestinationConnector(BaseConnector):file_execution_id: str,meta_data: dict[str, Any] | None = None,ttl_seconds: int | None = None,+ hitl_reason: str | None = None,) -> dict[str, Any]:"""Create QueueResult dictionary.@@ -944,6 +982,7 @@ class DestinationConnector(BaseConnector):file_execution_id: File execution IDmeta_data: Optional metadatattl_seconds: Optional TTL in seconds+ hitl_reason: Optional reason why file was sent to HITLReturns:QueueResult as dictionary@@ -961,6 +1000,7 @@ class DestinationConnector(BaseConnector):file_execution_id=file_execution_id,extracted_text=extracted_text,ttl_seconds=ttl_seconds,+ hitl_reason=hitl_reason,)return queue_result_obj.to_dict()diff --git a/backend/workflow_manager/endpoint_v2/queue_utils.py b/backend/workflow_manager/endpoint_v2/queue_utils.pyindex cda73fbe1..a3745216d 100644--- a/backend/workflow_manager/endpoint_v2/queue_utils.py+++ b/backend/workflow_manager/endpoint_v2/queue_utils.py@@ -98,6 +98,7 @@ class QueueResult:enqueued_at: float | None = Nonettl_seconds: int | None = Noneextracted_text: str | None = None+ hitl_reason: str | None = Nonedef __post_init__(self):"""Initialize enqueued_at timestamp if not provided and validate required fields"""@@ -124,5 +125,6 @@ class QueueResult:"enqueued_at": self.enqueued_at,"ttl_seconds": self.ttl_seconds,"extracted_text": self.extracted_text,+ "hitl_reason": self.hitl_reason,}return result_dictdiff --git a/frontend/src/components/agency/configure-connector-modal/ConfigureConnectorModal.jsx b/frontend/src/components/agency/configure-connector-modal/ConfigureConnectorModal.jsxindex b146bc5d6..8e75ef847 100644--- a/frontend/src/components/agency/configure-connector-modal/ConfigureConnectorModal.jsx+++ b/frontend/src/components/agency/configure-connector-modal/ConfigureConnectorModal.jsx@@ -25,14 +25,17 @@ import { CustomButton } from "../../widgets/custom-button/CustomButton";import { ConfigureFormsLayout } from "../configure-forms-layout/ConfigureFormsLayout";import "./ConfigureConnectorModal.css";-let DBRules;+let RuleEngine;+let ruleEngineTabs;try {- DBRules =- require("../../../plugins/manual-review/db-rules/DBRules.jsx").DBRules;+ const ruleEnginePlugin = require("../../../plugins/manual-review/rule-engine");+ RuleEngine = ruleEnginePlugin.RuleEngine;+ ruleEngineTabs = ruleEnginePlugin.ruleEngineTabs;} catch {- // The component will remain null of it is not available+ // Plugin not available}+function ConfigureConnectorModal({open,setOpen,@@ -378,22 +381,17 @@ function ConfigureConnectorModal({};// Load plugin tab for Human In The Loop (DATABASE connectors only)+ // API connectors show RuleEngine directly without tabsuseEffect(() => {- if (connMode !== "DATABASE") {+ if (connMode !== "DATABASE" || !ruleEngineTabs) {return;}- try {- const tabOption =- require("../../../plugins/manual-review/connector-config-tab-mrq/ConnectorConfigTabMRQ").mrqTabs;- if (tabOption) {- tabOption["disabled"] = !connDetails?.id;- tabOption["visible"] = true;- setUpdatedTabOptions(tabOption);- }- } catch {- // The component will remain null if it is not available- }+ // Use tab configuration from the rule-engine plugin+ const tabOption = { ...ruleEngineTabs };+ tabOption["disabled"] = !connDetails?.id;+ tabOption["visible"] = true;+ setUpdatedTabOptions(tabOption);}, [connMode, connDetails?.id]);// Handle click-outside to clear file selection@@ -496,17 +494,19 @@ function ConfigureConnectorModal({closable={!isSavingEndpoint}centeredfooter={- connDetails?.id ? (+ connDetails?.id || connMode === "API" ? (<div className="conn-modal-footer"><Button onClick={handleModalClose}>Cancel</Button>- <Button- type="primary"- loading={isSavingEndpoint}- onClick={handleSave}- disabled={!hasUnsavedChanges()}- >- Save- </Button>+ {connMode !== "API" && (+ <Button+ type="primary"+ loading={isSavingEndpoint}+ onClick={handleSave}+ disabled={!hasUnsavedChanges()}+ >+ Save+ </Button>+ )}</div>) : null}@@ -515,61 +515,63 @@ function ConfigureConnectorModal({><div className="conn-modal-body"><Typography.Text className="modal-header" strong>- Configure Connector+ {connMode === "API" ? "Configure HITL Rules" : "Configure Connector"}</Typography.Text>- {/* Connector Selection Dropdown */}- <div className="connector-selection-section">- <Typography.Text strong className="connector-selection-label">- Select Connector- </Typography.Text>- <Select- className="connector-selection-dropdown"- placeholder="Select a connector"- showSearch- filterOption={(input, option) => {- return option?.data?.label- ?.toLowerCase()- .includes(input.toLowerCase());- }}- value={- connDetails?.id- ? {- value: connDetails.id,- label: renderConnectorLabel(- connDetails,- availableConnectors- ),- }- : undefined- }- labelInValue- onChange={(option) => handleConnectorSelect(option?.value)}- loading={isLoadingConnectors}- options={availableConnectors.map((conn) => ({- value: conn.value,- label: (- <Space>- {conn.icon && !conn.isAddNew && (- <Image- src={conn.icon}- width={20}- height={20}- preview={false}- />- )}- <span>{conn.label}</span>- </Space>- ),- data: conn,- }))}- optionRender={(option) => option.label}- dropdownRender={renderDropdown}- />- </div>+ {/* Connector Selection Dropdown (not shown for API connectors) */}+ {connMode !== "API" && (+ <div className="connector-selection-section">+ <Typography.Text strong className="connector-selection-label">+ Select Connector+ </Typography.Text>+ <Select+ className="connector-selection-dropdown"+ placeholder="Select a connector"+ showSearch+ filterOption={(input, option) => {+ return option?.data?.label+ ?.toLowerCase()+ .includes(input.toLowerCase());+ }}+ value={+ connDetails?.id+ ? {+ value: connDetails.id,+ label: renderConnectorLabel(+ connDetails,+ availableConnectors+ ),+ }+ : undefined+ }+ labelInValue+ onChange={(option) => handleConnectorSelect(option?.value)}+ loading={isLoadingConnectors}+ options={availableConnectors.map((conn) => ({+ value: conn.value,+ label: (+ <Space>+ {conn.icon && !conn.isAddNew && (+ <Image+ src={conn.icon}+ width={20}+ height={20}+ preview={false}+ />+ )}+ <span>{conn.label}</span>+ </Space>+ ),+ data: conn,+ }))}+ optionRender={(option) => option.label}+ dropdownRender={renderDropdown}+ />+ </div>+ )}- {/* Show placeholder when no connector is selected */}- {!connDetails?.id && (+ {/* Show placeholder when no connector is selected (not for API connectors) */}+ {!connDetails?.id && connMode !== "API" && (<div className="connector-placeholder">{connType === "input" ? (<CloudDownloadOutlined className="connector-placeholder-icon" />@@ -582,8 +584,13 @@ function ConfigureConnectorModal({</div>)}+ {/* API connectors: Show only HITL rules (no connector selection needed) */}+ {connMode === "API" && RuleEngine && (+ <RuleEngine workflowDetails={workflowDetails} ruleType="API" />+ )}+{/* Only show configuration form and file browser after a connector is selected */}- {connDetails?.id && (+ {connDetails?.id && connMode !== "API" && (<>{/* DATABASE connectors: Show tabs with Settings and Human In The Loop */}{connMode === "DATABASE" ? (@@ -609,8 +616,11 @@ function ConfigureConnectorModal({validateAndSubmit={handleValidateAndSubmit}/>)}- {item.key === "MANUALREVIEW" && DBRules && (- <DBRules workflowDetails={workflowDetails} />+ {item.key === "MANUALREVIEW" && RuleEngine && (+ <RuleEngine+ workflowDetails={workflowDetails}+ ruleType="DB"+ />)}</>),diff --git a/frontend/src/components/agency/ds-settings-card/DsSettingsCard.jsx b/frontend/src/components/agency/ds-settings-card/DsSettingsCard.jsxindex a70654a48..3e8d51546 100644--- a/frontend/src/components/agency/ds-settings-card/DsSettingsCard.jsx+++ b/frontend/src/components/agency/ds-settings-card/DsSettingsCard.jsx@@ -257,11 +257,13 @@ function DsSettingsCard({ connType, endpointDetails, message }) {onClick={() => setOpenModal(true)}disabled={!endpointDetails?.connection_type ||- connMode === "API" ||- connMode === "APPDEPLOYMENT"+ connMode === "APPDEPLOYMENT" ||+ (connMode === "API" && connType === "input")}>- Configure+ {connMode === "API" && connType === "output"+ ? "Configure HITL"+ : "Configure"}</Button></Tooltip></Space>diff --git a/workers/api-deployment/tasks.py b/workers/api-deployment/tasks.pyindex 46f8704ba..5345d41d5 100644--- a/workers/api-deployment/tasks.py+++ b/workers/api-deployment/tasks.py@@ -838,18 +838,33 @@ def _create_file_data("rule_json": None,}- # ARCHITECTURE FIX: Skip manual review DB rules for API deployments- # API deployments handle manual review through different mechanisms (if supported)- # The DB rules endpoint is designed for ETL workflows, not API deployments- logger.info(- "API deployment workflow detected - skipping manual review DB rules lookup"- )-- # For future: API deployments could support manual review through other mechanisms- # such as workflow-specific configuration or query parameters passed in the API request- logger.info(- f"No manual review rules configured for API deployment workflow {workflow_id}"- )+ # Fetch API rules for this workflow (rule_type="API" for API deployments)+ try:+ rule_response = api_client.manual_review_client.get_rule_engine_data(+ workflow_id=workflow_id,+ _organization_id=organization_id,+ rule_type="API",+ )+ if rule_response and rule_response.success:+ rule_data = rule_response.data or {}+ if rule_data.get("review_required") or rule_data.get("percentage", 0) > 0:+ manual_review_config = {+ "review_required": rule_data.get("review_required", False),+ "review_percentage": rule_data.get("percentage", 0),+ "rule_logic": rule_data.get("rule_logic"),+ "rule_json": rule_data.get("rule_json"),+ }+ logger.info(+ f"API rules configured for workflow {workflow_id}: "+ f"percentage={manual_review_config['review_percentage']}, "+ f"rule_logic={manual_review_config['rule_logic']}"+ )+ else:+ logger.info(f"No API rules configured for workflow {workflow_id}")+ else:+ logger.info(f"No API rules found for workflow {workflow_id}")+ except Exception as e:+ logger.warning(f"Failed to fetch API rules for workflow {workflow_id}: {e}")hitl_queue_name = kwargs.get("hitl_queue_name")hitl_packet_id = kwargs.get("hitl_packet_id")llm_profile_id = kwargs.get("llm_profile_id")diff --git a/workers/shared/clients/manual_review_stub.py b/workers/shared/clients/manual_review_stub.pyindex 9768a64d9..6b3662476 100644--- a/workers/shared/clients/manual_review_stub.py+++ b/workers/shared/clients/manual_review_stub.py@@ -71,26 +71,42 @@ class ManualReviewNullClient:message="Manual review not available in OSS - no files selected for review",)- def get_db_rules_data(- self, workflow_id: str, _organization_id: str | None = None+ def get_rule_engine_data(+ self, workflow_id: str, _organization_id: str | None = None, rule_type: str = "DB") -> ManualReviewResponse:- """Get database rules for manual review (returns no rules in OSS).+ """Get rule engine data for manual review (returns no rules in OSS).Args:workflow_id: Workflow ID_organization_id: Organization ID (unused in stub)+ rule_type: Rule type (DB or API, unused in stub)Returns:ManualReviewResponse indicating no manual review rules are configured"""logger.debug(- f"ManualReviewNullClient: get_db_rules_data called for workflow {workflow_id} - returning no rules"+ f"ManualReviewNullClient: get_rule_engine_data called for workflow {workflow_id} - returning no rules")return ManualReviewResponse.success_response(- data={"rules": [], "percentage": 0, "review_required": False},+ data={+ "rules": [],+ "percentage": 0,+ "review_required": False,+ "rule_type": rule_type,+ },message="Manual review not available in OSS - no rules configured",)+ # Backward compatibility alias+ def get_db_rules_data(+ self, workflow_id: str, _organization_id: str | None = None+ ) -> ManualReviewResponse:+ """Get database rules for manual review (returns no rules in OSS).++ Deprecated: Use get_rule_engine_data instead.+ """+ return self.get_rule_engine_data(workflow_id, _organization_id, rule_type="DB")+def enqueue_manual_review(self, *args, **kwargs) -> dict[str, Any]:"""Enqueue item for manual review (no-op in OSS).@@ -212,20 +228,34 @@ class ManualReviewNullClient:"item": None,}- def validate_manual_review_db_rule(self, *args, **kwargs) -> dict[str, Any]:- """Validate manual review database rule (no-op in OSS).+ def validate_rule_engine(+ self, *args, rule_type: str = "DB", **kwargs+ ) -> dict[str, Any]:+ """Validate rule engine (no-op in OSS).++ Args:+ rule_type: Rule type (DB or API)Returns:Dictionary indicating validation is not available"""logger.debug(- "ManualReviewNullClient: validate_manual_review_db_rule called - not available in OSS"+ f"ManualReviewNullClient: validate_rule_engine called (rule_type={rule_type}) - not available in OSS")return {"valid": False,"message": "Manual review validation not available in OSS version",+ "rule_type": rule_type,}+ # Backward compatibility alias+ def validate_manual_review_db_rule(self, *args, **kwargs) -> dict[str, Any]:+ """Validate manual review database rule (no-op in OSS).++ Deprecated: Use validate_rule_engine instead.+ """+ return self.validate_rule_engine(*args, rule_type="DB", **kwargs)+def get_hitl_settings(self, workflow_id: str, organization_id: str | None = None) -> dict[str, Any]:diff --git a/workers/shared/models/result_models.py b/workers/shared/models/result_models.pyindex 99fa04432..48bb932e1 100644--- a/workers/shared/models/result_models.py+++ b/workers/shared/models/result_models.py@@ -226,6 +226,7 @@ class QueueResult:enqueued_at: float | None = Nonettl_seconds: int | None = Noneextracted_text: str | None = None+ hitl_reason: str | None = Nonedef __post_init__(self):"""Initialize enqueued_at timestamp if not provided and validate required fields"""@@ -252,5 +253,6 @@ class QueueResult:"enqueued_at": self.enqueued_at,"ttl_seconds": self.ttl_seconds,"extracted_text": self.extracted_text,+ "hitl_reason": self.hitl_reason,}return result_dictdiff --git a/workers/shared/utils/manual_review_factory.py b/workers/shared/utils/manual_review_factory.pyindex 8f1c40942..69c101155 100644--- a/workers/shared/utils/manual_review_factory.py+++ b/workers/shared/utils/manual_review_factory.py@@ -122,6 +122,18 @@ class ManualReviewNullService:# OSS: No manual review queuereturn None+ @staticmethod+ def validate_rule_engine(+ result,+ workflow_id,+ file_destination,+ is_manual_review_required,+ rule_type="DB",+ ):+ # OSS: No rule validation+ return False++ # Backward compatibility alias@staticmethoddef validate_db_rule(result, workflow_id, file_destination, is_manual_review_required@@ -129,6 +141,11 @@ class ManualReviewNullService:# OSS: No rule validationreturn False+ @staticmethod+ def has_api_rules(workflow):+ # OSS: No API rules support+ return False+@staticmethoddef get_hitl_ttl_seconds(workflow):# OSS: No TTL restrictions@@ -296,12 +313,37 @@ class ManualReviewEnhancedService:def get_q_no_list(workflow, total_files):return None+ @staticmethod+ def validate_rule_engine(+ result,+ workflow_id,+ file_destination,+ is_manual_review_required,+ rule_type="DB",+ ):+ return False++ @staticmethod+ def validate_rule_engine_with_reason(+ result,+ workflow_id,+ file_destination,+ is_manual_review_required,+ rule_type="DB",+ ):+ return {"matched": False, "reason": "HITL plugin not available"}++ # Backward compatibility alias@staticmethoddef validate_db_rule(result, workflow_id, file_destination, is_manual_review_required):return False+ @staticmethod+ def has_api_rules(workflow):+ return False+@staticmethoddef get_hitl_ttl_seconds(workflow):return None@@ -360,12 +402,37 @@ def _create_null_workflow_util():def get_q_no_list(workflow, total_files):return None+ @staticmethod+ def validate_rule_engine(+ result,+ workflow_id,+ file_destination,+ is_manual_review_required,+ rule_type="DB",+ ):+ return False++ @staticmethod+ def validate_rule_engine_with_reason(+ result,+ workflow_id,+ file_destination,+ is_manual_review_required,+ rule_type="DB",+ ):+ return {"matched": False, "reason": "HITL plugin not available"}++ # Backward compatibility alias@staticmethoddef validate_db_rule(result, workflow_id, file_destination, is_manual_review_required):return False+ @staticmethod+ def has_api_rules(workflow):+ return False+def create_workflow_file_data_with_manual_review(self,worker_file_data: WorkerFileData,diff --git a/workers/shared/workflow/destination_connector.py b/workers/shared/workflow/destination_connector.pyindex 3df8338fb..97851c9b8 100644--- a/workers/shared/workflow/destination_connector.py+++ b/workers/shared/workflow/destination_connector.py@@ -96,6 +96,14 @@ class FileContext:execution_error: str | None = None+@dataclass+class HITLDecision:+ """Result of HITL routing decision."""++ should_route_to_hitl: bool = False+ reason: str | None = None # Human-readable reason for the decision++@dataclassclass ProcessingResult:"""Result of destination processing."""@@ -103,6 +111,7 @@ class ProcessingResult:tool_execution_result: dict | str | None = Nonemetadata: dict[str, Any] | None = Nonehas_hitl: bool = False+ hitl_reason: str | None = None # Reason why file was sent to HITL@dataclass@@ -267,6 +276,68 @@ class WorkerDestinationConnector:return None+ def _prepare_result_for_rule_evaluation(+ self, file_name: str, tool_execution_result: dict | str | None+ ) -> dict | None:+ """Prepare result for rule evaluation by wrapping in expected structure.++ The rule engine expects: {"output": {...}, "metadata": {...}}++ Args:+ file_name: Name of the file (for logging)+ tool_execution_result: Raw tool execution result++ Returns:+ Wrapped result dict or None if no result+ """+ if not tool_execution_result:+ return None++ if not isinstance(tool_execution_result, dict):+ logger.warning(+ f"{file_name}: tool_execution_result is not a dict: {type(tool_execution_result)}"+ )+ return None++ # Check if tool_execution_result already has the correct structure+ if "output" in tool_execution_result:+ # Already in correct format with metadata - use directly+ return tool_execution_result++ # Legacy format: wrap in expected structure+ metadata = self.get_metadata()++ # 3-tier fallback hierarchy for confidence:+ # 1. word_confidence_data (if available)+ # 2. Extract from 5th element of highlight_data+ # 3. confidence_data (last resort)+ highlight_data = metadata.get("highlight_data", {}) if metadata else {}+ word_confidence_data = (+ metadata.get("word_confidence_data", {}) if metadata else {}+ )+ confidence_data = metadata.get("confidence_data", {}) if metadata else {}++ # If word_confidence_data is not available, try extracting from highlight_data+ if not word_confidence_data and highlight_data:+ extracted_confidence = self._extract_confidence_from_highlight_data(+ highlight_data+ )+ # Use extracted confidence if available, otherwise fall back to confidence_data+ if extracted_confidence is not None:+ # For rule engine, we provide a single confidence score+ confidence_data = {"_extracted_average": extracted_confidence}++ return {+ "output": tool_execution_result,+ "metadata": {+ "confidence_data": confidence_data,+ "word_confidence_data": word_confidence_data,+ "highlight_data": highlight_data,+ "whisper-hash": metadata.get("whisper-hash") if metadata else None,+ "extracted_text": metadata.get("extracted_text") if metadata else None,+ },+ }+@classmethoddef from_config(cls, workflow_log, config: DestinationConfig):"""Create destination connector from config (matching Django backend interface)."""@@ -493,9 +564,13 @@ class WorkerDestinationConnector:exec_ctx: ExecutionContext,file_ctx: FileContext,result: ProcessingResult,- ) -> bool:- """Check HITL requirements and push to queue if needed."""- has_hitl = self._should_handle_hitl(+ ) -> HITLDecision:+ """Check HITL requirements and push to queue if needed.++ Returns:+ HITLDecision: Decision object with should_route_to_hitl flag and reason+ """+ hitl_decision = self._should_handle_hitl(file_name=file_ctx.file_name,file_hash=file_ctx.file_hash,workflow=file_ctx.workflow,@@ -504,7 +579,11 @@ class WorkerDestinationConnector:error=file_ctx.execution_error,)- if has_hitl:+ # Update result with HITL metadata+ result.has_hitl = hitl_decision.should_route_to_hitl+ result.hitl_reason = hitl_decision.reason++ if hitl_decision.should_route_to_hitl:self._push_data_to_queue(file_name=file_ctx.file_name,workflow=file_ctx.workflow,@@ -512,9 +591,10 @@ class WorkerDestinationConnector:file_execution_id=exec_ctx.file_execution_id,tool_execution_result=result.tool_execution_result,api_client=exec_ctx.api_client,+ hitl_reason=hitl_decision.reason,)- return has_hitl+ return hitl_decisiondef _process_destination(self,@@ -549,6 +629,14 @@ class WorkerDestinationConnector:f"🔌 File '{file_ctx.file_name}' marked for API processing - preparing response",)+ # Prepare metadata - add HITL info only if plugin is available (cloud feature)+ api_metadata = result.metadata.copy() if result.metadata else {}+ if has_manual_review_plugin():+ api_metadata["hitl"] = {+ "file_sent_to_hitl": result.has_hitl,+ "reason": result.hitl_reason,+ }+self.cache_api_result(api_client=exec_ctx.api_client,file_hash=file_ctx.file_hash,@@ -558,7 +646,7 @@ class WorkerDestinationConnector:file_execution_id=exec_ctx.file_execution_id,organization_id=exec_ctx.organization_id,error=file_ctx.execution_error,- metadata=result.metadata,+ metadata=api_metadata,)def _handle_filesystem_destination(@@ -636,6 +724,7 @@ class WorkerDestinationConnector:file_execution_id=exec_ctx.file_execution_id,tool_execution_result=result.tool_execution_result,api_client=exec_ctx.api_client,+ hitl_reason="Destination configured for manual review",)def _handle_destination_error(@@ -766,8 +855,8 @@ class WorkerDestinationConnector:# Only extract data if lock was acquired (not a duplicate)result = self._extract_processing_data(exec_ctx, file_ctx)- # Check and handle HITL if needed- result.has_hitl = self._check_and_handle_hitl(exec_ctx, file_ctx, result)+ # Check and handle HITL if needed (this updates result.has_hitl and result.hitl_reason)+ self._check_and_handle_hitl(exec_ctx, file_ctx, result)# Process through appropriate destinationtry:@@ -1428,29 +1517,88 @@ class WorkerDestinationConnector:api_client: Optional["InternalAPIClient"] = None,tool_execution_result: dict | str | None = None,error: str | None = None,- ) -> bool:- """Determines if HITL processing should be performed, returning True if data was pushed to the queue.+ ) -> HITLDecision:+ """Determines if HITL processing should be performed.This method replicates the backend DestinationConnector._should_handle_hitl logic.++ The logic is:+ 1. hitl_packet_id takes precedence - always push to packet queue+ 2. hitl_queue_name with API rules:+ - If no API rules configured → Push ALL to HITL (backward compatible)+ - If API rules exist → Evaluate rules, push only if rules match+ 3. Database destination → Evaluate DB rules++ Returns:+ HITLDecision: Decision object with should_route_to_hitl flag and reason"""logger.info(f"{file_name}: checking if file is eligible for HITL")if error:logger.error(f"{file_name}: file is not eligible for HITL due to error: {error}")- return False+ return HITLDecision(False, f"Processing error: {error}")# Check hitl_packet_id first - it takes precedence over everything elseif self.hitl_packet_id:logger.info(f"API packet override: pushing to packet queue for file {file_name}")- return True+ return HITLDecision(True, f"HITL packet ID specified: {self.hitl_packet_id}")- # Check if API deployment requested HITL override+ # Check if API deployment requested HITL override with hitl_queue_nameif self.hitl_queue_name:- logger.info(f"{file_name}: Pushing to HITL queue")- return True+ logger.info(+ f"{file_name}: HITL queue name detected: {self.hitl_queue_name}. "+ f"Checking for API rules..."+ )+ # Get workflow util to check for API rules+ manual_review_service = self._ensure_manual_review_service(api_client)+ if manual_review_service:+ workflow_util = manual_review_service.get_workflow_util()+ has_rules = workflow_util.has_api_rules(workflow)+ logger.info(f"{file_name}: has_api_rules={has_rules}")++ if has_rules:+ # API rules exist - evaluate them+ wrapped_result = self._prepare_result_for_rule_evaluation(+ file_name, tool_execution_result+ )+ logger.info(+ f"{file_name}: Evaluating API rules. "+ f"wrapped_result type={type(wrapped_result).__name__}, "+ f"has_output={bool(wrapped_result.get('output') if wrapped_result else False)}"+ )+ # Get detailed rule evaluation result+ rule_result = workflow_util.validate_rule_engine_with_reason(+ wrapped_result,+ workflow,+ file_hash.file_destination,+ file_hash.is_manualreview_required,+ rule_type="API",+ )+ if rule_result.get("matched", False):+ reason = rule_result.get("reason", "API rules matched")+ logger.info(+ f"{file_name}: API rules matched - pushing to HITL queue. Reason: {reason}"+ )+ return HITLDecision(True, reason)+ else:+ reason = rule_result.get("reason", "API rules not matched")+ logger.info(+ f"{file_name}: API rules not matched - returning result directly. Reason: {reason}"+ )+ return HITLDecision(False, reason)+ else:+ logger.warning(f"{file_name}: No manual review service available")++ # No API rules configured - backward compatible behavior: push ALL to HITL+ logger.info(+ f"{file_name}: No API rules configured - pushing ALL to HITL queue (backward compatible)"+ )+ return HITLDecision(+ True, "HITL queue specified, no rules configured - sending all to HITL"+ )# Skip HITL validation if we're using file_history and no execution result is available# CRITICAL FIX: Only skip HITL validation for API deployments without file history@@ -1459,7 +1607,9 @@ class WorkerDestinationConnector:logger.info(f"{file_name}: Skipping HITL validation for API deployment without file history")- return False+ return HITLDecision(+ False, "API deployment without file history - HITL not applicable"+ )# For API deployments WITH file history, continue to evaluate rules# For ETL workflows, ALWAYS evaluate rules (regardless of file_history)@@ -1468,87 +1618,37 @@ class WorkerDestinationConnector:manual_review_service = self._ensure_manual_review_service(api_client)if not manual_review_service:logger.info(f"No manual review service available for {file_name}")- return False+ return HITLDecision(False, "Manual review service not available")workflow_util = manual_review_service.get_workflow_util()# Don't skip rule evaluation just because file wasn't pre-selected by percentage- # validate_db_rule will check both percentage selection AND rules with OR/AND logic+ # validate_rule_engine will check both percentage selection AND rules with OR/AND logicif not file_hash.is_manualreview_required:logger.info(f"{file_name}: File not pre-selected by percentage, "f"but checking if rules match...")- # Prepare result for rule evaluation- # validate_db_rule expects: {"output": {...}, "metadata": {...}}- # Note: tool_execution_result from JSON output already has correct structure- wrapped_result = None- if tool_execution_result:- if isinstance(tool_execution_result, dict):- # Check if tool_execution_result already has the correct structure- if "output" in tool_execution_result:- # Already in correct format with metadata - use directly- wrapped_result = tool_execution_result- else:- # Legacy format: wrap in expected structure- metadata = self.get_metadata()-- # 3-tier fallback hierarchy for confidence:- # 1. word_confidence_data (if available)- # 2. Extract from 5th element of highlight_data- # 3. confidence_data (last resort)- highlight_data = (- metadata.get("highlight_data", {}) if metadata else {}- )- word_confidence_data = (- metadata.get("word_confidence_data", {}) if metadata else {}- )- confidence_data = (- metadata.get("confidence_data", {}) if metadata else {}- )-- # If word_confidence_data is not available, try extracting from highlight_data- if not word_confidence_data and highlight_data:- extracted_confidence = (- self._extract_confidence_from_highlight_data(highlight_data)- )- # Use extracted confidence if available, otherwise fall back to confidence_data- # Store as a simple dict for compatibility- if extracted_confidence is not None:- # For rule engine, we provide a single confidence score- # This will be used by the enterprise plugin- confidence_data = {"_extracted_average": extracted_confidence}-- wrapped_result = {- "output": tool_execution_result,- "metadata": {- "confidence_data": confidence_data,- "word_confidence_data": word_confidence_data,- "highlight_data": highlight_data,- "whisper-hash": metadata.get("whisper-hash")- if metadata- else None,- "extracted_text": metadata.get("extracted_text")- if metadata- else None,- },- }- else:- logger.warning(- f"{file_name}: tool_execution_result is not a dict: {type(tool_execution_result)}"- )+ # Prepare result for rule evaluation using helper method+ wrapped_result = self._prepare_result_for_rule_evaluation(+ file_name, tool_execution_result+ )- is_to_hitl = workflow_util.validate_db_rule(+ # Evaluate DB rules for ETL workflows with reason+ rule_result = workflow_util.validate_rule_engine_with_reason(wrapped_result,workflow,file_hash.file_destination,file_hash.is_manualreview_required,+ rule_type="DB",+ )+ is_to_hitl = rule_result.get("matched", False)+ reason = rule_result.get("reason", "DB rules evaluation")+ logger.info(+ f"File {file_name} checked for manual review: {is_to_hitl}, reason: {reason}")- logger.info(f"File {file_name} checked for manual review: {is_to_hitl}")- if is_to_hitl:- return True- return False+ return HITLDecision(is_to_hitl, reason)def _enqueue_to_packet_or_regular_queue(self,@@ -1627,6 +1727,7 @@ class WorkerDestinationConnector:file_execution_id: str,tool_execution_result: str = None,api_client: Optional["InternalAPIClient"] = None,+ hitl_reason: str | None = None,) -> None:"""Handle manual review queue processing (following production pattern).@@ -1697,6 +1798,7 @@ class WorkerDestinationConnector:file_execution_id=file_execution_id,extracted_text=extracted_text,ttl_seconds=ttl_seconds,+ hitl_reason=hitl_reason,)# Only include file_content if provided (backend API will handle it)