Skip to content

LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows

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.py
index 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
+
@staticmethod
def 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 containing
confidence_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 of
the file (e.g., MANUALREVIEW or other).
@@ -80,6 +106,21 @@ class WorkflowUtil:
bool: True if the field_key conditions are met based on rule logic
and 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
@staticmethod
diff --git a/backend/workflow_manager/endpoint_v2/destination.py b/backend/workflow_manager/endpoint_v2/destination.py
index 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_name
if 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_name
if 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 available
if 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 destinations
execution_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 ID
meta_data: Optional metadata
ttl_seconds: Optional TTL in seconds
+ hitl_reason: Optional reason why file was sent to HITL
Returns:
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.py
index 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 = None
ttl_seconds: int | None = None
extracted_text: str | None = None
+ hitl_reason: str | None = None
def __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_dict
diff --git a/frontend/src/components/agency/configure-connector-modal/ConfigureConnectorModal.jsx b/frontend/src/components/agency/configure-connector-modal/ConfigureConnectorModal.jsx
index 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 tabs
useEffect(() => {
- 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}
centered
footer={
- 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.jsx
index 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.py
index 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.py
index 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.py
index 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 = None
ttl_seconds: int | None = None
extracted_text: str | None = None
+ hitl_reason: str | None = None
def __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_dict
diff --git a/workers/shared/utils/manual_review_factory.py b/workers/shared/utils/manual_review_factory.py
index 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 queue
return 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
@staticmethod
def validate_db_rule(
result, workflow_id, file_destination, is_manual_review_required
@@ -129,6 +141,11 @@ class ManualReviewNullService:
# OSS: No rule validation
return False
+ @staticmethod
+ def has_api_rules(workflow):
+ # OSS: No API rules support
+ return False
+
@staticmethod
def 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
@staticmethod
def validate_db_rule(
result, workflow_id, file_destination, is_manual_review_required
):
return False
+ @staticmethod
+ def has_api_rules(workflow):
+ return False
+
@staticmethod
def 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
@staticmethod
def 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.py
index 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
+
+
@dataclass
class ProcessingResult:
"""Result of destination processing."""
@@ -103,6 +111,7 @@ class ProcessingResult:
tool_execution_result: dict | str | None = None
metadata: dict[str, Any] | None = None
has_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,
+ },
+ }
+
@classmethod
def 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_decision
def _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 destination
try:
@@ -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 else
if 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_name
if 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 logic
if 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)