griptape-nodes 0.52.1__py3-none-any.whl → 0.54.0__py3-none-any.whl

griptape_nodes/exe_types/node_types.py

@@ -6,12 +6,13 @@ from abc import ABC, abstractmethod
 from collections.abc import Callable, Generator, Iterable
 from concurrent.futures import ThreadPoolExecutor
 from enum import StrEnum, auto
-from typing import Any, NamedTuple, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from griptape_nodes.exe_types.core_types import (
     BaseNodeElement,
     ControlParameterInput,
     ControlParameterOutput,
+    NodeMessageResult,
     Parameter,
     ParameterContainer,
     ParameterDictionary,
@@ -21,6 +22,7 @@ from griptape_nodes.exe_types.core_types import (
     ParameterMode,
     ParameterTypeBuiltin,
 )
+from griptape_nodes.exe_types.param_components.execution_status_component import ExecutionStatusComponent
 from griptape_nodes.exe_types.type_validator import TypeValidator
 from griptape_nodes.retained_mode.events.base_events import (
     ExecutionEvent,
@@ -39,6 +41,9 @@ from griptape_nodes.retained_mode.events.parameter_events import (
 )
 from griptape_nodes.traits.options import Options
 
+if TYPE_CHECKING:
+    from griptape_nodes.exe_types.core_types import NodeMessagePayload
+
 logger = logging.getLogger("griptape_nodes")
 
 T = TypeVar("T")
@@ -54,23 +59,6 @@ class NodeResolutionState(StrEnum):
     RESOLVED = auto()
 
 
-class NodeMessageResult(NamedTuple):
-    """Result from a node message callback.
-
-    Attributes:
-        success: True if the message was handled successfully, False otherwise
-        details: Human-readable description of what happened
-        response: Optional response data to return to the sender
-        altered_workflow_state: True if the message handling altered workflow state.
-            Clients can use this to determine if the workflow needs to be re-saved.
-    """
-
-    success: bool
-    details: str
-    response: Any = None
-    altered_workflow_state: bool = True
-
-
 class BaseNode(ABC):
     # Owned by a flow
     name: str
@@ -80,7 +68,7 @@ class BaseNode(ABC):
     state: NodeResolutionState
     current_spotlight_parameter: Parameter | None = None
     parameter_values: dict[str, Any]
-    parameter_output_values: dict[str, Any]
+    parameter_output_values: TrackedParameterOutputValues
     stop_flow: bool = False
     root_ui_element: BaseNodeElement
     _tracked_parameters: list[BaseNodeElement]
@@ -289,15 +277,18 @@ class BaseNode(ABC):
 
     def on_node_message_received(
         self,
-        optional_element_name: str | None,  # noqa: ARG002
+        optional_element_name: str | None,
         message_type: str,
-        message: Any,  # noqa: ARG002
+        message: NodeMessagePayload | None,
     ) -> NodeMessageResult:
         """Callback for when a message is sent directly to this node.
 
         Custom nodes may elect to override this method to handle specific message types
         and implement custom communication patterns with external systems.
 
+        If optional_element_name is provided, this method will attempt to find the
+        element and delegate the message handling to that element's on_message_received method.
+
         Args:
             optional_element_name: Optional element name this message relates to
             message_type: String indicating the message type for parsing
@@ -306,6 +297,26 @@ class BaseNode(ABC):
         Returns:
             NodeMessageResult: Result containing success status, details, and optional response
         """
+        # If optional_element_name is provided, delegate to the specific element
+        if optional_element_name is not None:
+            element = self.root_ui_element.find_element_by_name(optional_element_name)
+            if element is None:
+                return NodeMessageResult(
+                    success=False,
+                    details=f"Node '{self.name}' received message for element '{optional_element_name}' but no element with that name was found",
+                    response=None,
+                )
+            # Delegate to the element's message handler
+            result = element.on_message_received(message_type, message)
+            if result is None:
+                return NodeMessageResult(
+                    success=False,
+                    details=f"Element '{optional_element_name}' received message type '{message_type}' but no handler was available",
+                    response=None,
+                )
+            return result
+
+        # If no element name specified, fall back to node-level handling
         return NodeMessageResult(
             success=False,
             details=f"Node '{self.name}' was sent a message of type '{message_type}'. Failed because no message handler was specified for this node. Implement the on_node_message_received method in this node class in order for it to receive messages.",
@@ -620,10 +631,10 @@ class BaseNode(ABC):
         # Allow custom node logic to prepare and possibly mutate the value before it is actually set.
         # Record any parameters modified for cascading.
         if not initial_setup:
-            if not skip_before_value_set:
-                final_value = self.before_value_set(parameter=parameter, value=candidate_value)
-            else:
+            if skip_before_value_set:
                 final_value = candidate_value
+            else:
+                final_value = self.before_value_set(parameter=parameter, value=candidate_value)
             # ACTUALLY SET THE NEW VALUE
             self.parameter_values[param_name] = final_value
 
@@ -705,6 +716,9 @@ class BaseNode(ABC):
             raise KeyError(err)
 
     def get_next_control_output(self) -> Parameter | None:
+        # The default behavior for nodes is to find the first control output found.
+        # Advanced nodes can override this behavior (e.g., nodes that have multiple possible
+        # control paths).
         for param in self.parameters:
             if (
                 ParameterTypeBuiltin.CONTROL_TYPE.value == param.output_type
@@ -1097,6 +1111,10 @@ class TrackedParameterOutputValues(dict[str, Any]):
             for key in keys_to_clear:
                 self._emit_parameter_change_event(key, None, deleted=True)
 
+    def silent_clear(self) -> None:
+        """Clear all values without emitting parameter change events."""
+        super().clear()
+
     def update(self, *args, **kwargs) -> None:
         # Handle both dict.update(other) and dict.update(**kwargs) patterns
         if args:
@@ -1136,28 +1154,185 @@ class TrackedParameterOutputValues(dict[str, Any]):
 
 class ControlNode(BaseNode):
     # Control Nodes may have one Control Input Port and at least one Control Output Port
+    def __init__(
+        self,
+        name: str,
+        metadata: dict[Any, Any] | None = None,
+        input_control_name: str | None = None,
+        output_control_name: str | None = None,
+    ) -> None:
+        super().__init__(name, metadata=metadata)
+        self.control_parameter_in = ControlParameterInput(
+            display_name=input_control_name if input_control_name is not None else "Flow In"
+        )
+        self.control_parameter_out = ControlParameterOutput(
+            display_name=output_control_name if output_control_name is not None else "Flow Out"
+        )
+
+        self.add_parameter(self.control_parameter_in)
+        self.add_parameter(self.control_parameter_out)
+
+
+class DataNode(BaseNode):
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
         super().__init__(name, metadata=metadata)
-        control_parameter_in = ControlParameterInput()
-        control_parameter_out = ControlParameterOutput()
 
-        self.add_parameter(control_parameter_in)
-        self.add_parameter(control_parameter_out)
+        # Create control parameters like ControlNode, but initialize them as hidden
+        # This allows the user to turn a DataNode "into" a Control Node; useful when
+        # in situations like within a For Loop.
+        self.control_parameter_in = ControlParameterInput()
+        self.control_parameter_out = ControlParameterOutput()
 
-    def get_next_control_output(self) -> Parameter | None:
-        for param in self.parameters:
-            if (
-                ParameterTypeBuiltin.CONTROL_TYPE.value == param.output_type
-                and ParameterMode.OUTPUT in param.allowed_modes
-            ):
-                return param
-        return None
+        # Hide the control parameters by default
+        self.control_parameter_in.ui_options["hide"] = True
+        self.control_parameter_out.ui_options["hide"] = True
 
+        self.add_parameter(self.control_parameter_in)
+        self.add_parameter(self.control_parameter_out)
+
+
+class SuccessFailureNode(BaseNode):
+    """Base class for nodes that have success/failure branching with control outputs.
+
+    This class provides:
+    - Control input parameter
+    - Two control outputs: success ("exec_out") and failure ("failure")
+    - Execution state tracking for control flow routing
+    - Helper method to check outgoing connections
+    - Helper method to create standard status output parameters
+    """
 
-class DataNode(BaseNode):
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
         super().__init__(name, metadata=metadata)
 
+        # Track execution state for control flow routing
+        self._execution_succeeded: bool | None = None
+
+        # Add control input parameter
+        self.control_parameter_in = ControlParameterInput()
+        self.add_parameter(self.control_parameter_in)
+
+        # Add success control output (uses default "exec_out" name)
+        self.control_parameter_out = ControlParameterOutput(
+            display_name="Succeeded", tooltip="Control path when the operation succeeds"
+        )
+        self.add_parameter(self.control_parameter_out)
+
+        # Add failure control output
+        self.failure_output = ControlParameterOutput(
+            name="failure",
+            display_name="Failed",
+            tooltip="Control path when the operation fails",
+        )
+        self.add_parameter(self.failure_output)
+
+    def get_next_control_output(self) -> Parameter | None:
+        """Determine which control output to follow based on execution result."""
+        if self._execution_succeeded is None:
+            # Execution hasn't completed yet
+            self.stop_flow = True
+            return None
+
+        if self._execution_succeeded:
+            return self.control_parameter_out
+        return self.failure_output
+
+    def _has_outgoing_connections(self, parameter: Parameter) -> bool:
+        """Check if a specific parameter has outgoing connections."""
+        from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+
+        connections = GriptapeNodes.FlowManager().get_connections()
+
+        # Check if node has any outgoing connections
+        node_connections = connections.outgoing_index.get(self.name)
+        if node_connections is None:
+            return False
+
+        # Check if this specific parameter has any outgoing connections
+        param_connections = node_connections.get(parameter.name, [])
+        return len(param_connections) > 0
+
+    def _create_status_parameters(
+        self,
+        result_details_tooltip: str = "Details about the operation result",
+        result_details_placeholder: str = "Details on the operation will be presented here.",
+    ) -> None:
+        """Create and add standard status output parameters in a collapsible group.
+
+        This method creates a "Status" ParameterGroup and immediately adds it to the node.
+        Nodes that use this are responsible for calling this at their desired location
+        in their class constructor.
+
+        Creates and adds:
+        - was_successful: Boolean parameter indicating success/failure
+        - result_details: String parameter with operation details
+
+        Args:
+            result_details_tooltip: Custom tooltip for result_details parameter
+            result_details_placeholder: Custom placeholder text for result_details parameter
+        """
+        # Create status component with OUTPUT modes for SuccessFailureNode
+        self.status_component = ExecutionStatusComponent(
+            self,
+            was_successful_modes={ParameterMode.OUTPUT},
+            result_details_modes={ParameterMode.OUTPUT},
+            parameter_group_initially_collapsed=True,
+            result_details_tooltip=result_details_tooltip,
+            result_details_placeholder=result_details_placeholder,
+        )
+
+    def _clear_execution_status(self) -> None:
+        """Clear execution status and reset status parameters.
+
+        This method should be called at the start of process() to reset the node state.
+        """
+        self._execution_succeeded = None
+        self.status_component.clear_execution_status("Beginning execution...")
+
+    def _set_status_results(self, *, was_successful: bool, result_details: str) -> None:
+        """Set status results and update execution state.
+
+        This method should be called from the process() method to communicate success or failure.
+        It sets the execution state for control flow routing and updates the status output parameters.
+
+        Args:
+            was_successful: Whether the operation succeeded
+            result_details: Details about the operation result
+        """
+        self._execution_succeeded = was_successful
+        self.status_component.set_execution_result(was_successful=was_successful, result_details=result_details)
+
+    def _handle_failure_exception(self, exception: Exception) -> None:
+        """Handle failure exceptions based on whether failure output is connected.
+
+        If the failure output has outgoing connections, logs the error and continues execution
+        to allow graceful failure handling. If no connections exist, raises the exception
+        to crash the flow and provide immediate feedback.
+
+        Args:
+            exception: The exception that caused the failure
+        """
+        if self._has_outgoing_connections(self.failure_output):
+            # User has connected something to Failed output, they want to handle errors gracefully
+            logger.error(
+                "Error in node '%s': %s. Continuing execution since failure output is connected for graceful handling.",
+                self.name,
+                exception,
+            )
+        else:
+            # No graceful handling, raise the exception to crash the flow
+            raise exception
+
+    def validate_before_workflow_run(self) -> list[Exception] | None:
+        """Clear result details before workflow runs to avoid confusion from previous sessions."""
+        self._set_status_results(was_successful=False, result_details="<Results will appear when the node executes>")
+        return super().validate_before_workflow_run()
+
+    def validate_before_node_run(self) -> list[Exception] | None:
+        """Clear result details before node runs to avoid confusion from previous sessions."""
+        self._set_status_results(was_successful=False, result_details="<Results will appear when the node executes>")
+        return super().validate_before_node_run()
+
 
 class StartNode(BaseNode):
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
@@ -1169,7 +1344,51 @@ class EndNode(BaseNode):
     # TODO: https://github.com/griptape-ai/griptape-nodes/issues/854
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
         super().__init__(name, metadata)
-        self.add_parameter(ControlParameterInput())
+
+        # Add dual control inputs
+        self.succeeded_control = ControlParameterInput(
+            display_name="Succeeded", tooltip="Control path when the flow completed successfully"
+        )
+        self.failed_control = ControlParameterInput(
+            name="failed", display_name="Failed", tooltip="Control path when the flow failed"
+        )
+
+        self.add_parameter(self.succeeded_control)
+        self.add_parameter(self.failed_control)
+
+        # Create status component with INPUT and PROPERTY modes
+        self.status_component = ExecutionStatusComponent(
+            self,
+            was_successful_modes={ParameterMode.PROPERTY},
+            result_details_modes={ParameterMode.INPUT},
+            parameter_group_initially_collapsed=False,
+            result_details_placeholder="Details about the completion or failure will be shown here.",
+        )
+
+    def process(self) -> None:
+        # Detect which control input was used to enter this node and determine success status
+        match self._entry_control_parameter:
+            case self.succeeded_control:
+                was_successful = True
+                status_prefix = "[SUCCEEDED]"
+            case self.failed_control:
+                was_successful = False
+                status_prefix = "[FAILED]"
+            case _:
+                # No specific success/failure connection provided, assume success
+                was_successful = True
+                status_prefix = "[SUCCEEDED] No connection provided for success or failure, assuming successful"
+
+        # Get result details and format the final message
+        result_details_value = self.get_parameter_value("result_details")
+        if result_details_value and self._entry_control_parameter in (self.succeeded_control, self.failed_control):
+            details = f"{status_prefix}\n{result_details_value}"
+        elif self._entry_control_parameter in (self.succeeded_control, self.failed_control):
+            details = f"{status_prefix}\nNo details supplied by flow"
+        else:
+            details = status_prefix
+
+        self.status_component.set_execution_result(was_successful=was_successful, result_details=details)
 
 
 class StartLoopNode(BaseNode):

griptape_nodes/exe_types/param_components/__init__.py

@@ -0,0 +1 @@
+"""Parameter components for reusable node functionality."""

griptape_nodes/exe_types/param_components/execution_status_component.py

@@ -0,0 +1,138 @@
+from typing import Any
+
+from griptape_nodes.exe_types.core_types import (
+    Parameter,
+    ParameterGroup,
+    ParameterMode,
+)
+
+
+class ExecutionStatusComponent:
+    """A reusable component for managing execution status parameters.
+
+    This component creates and manages a "Status" ParameterGroup containing:
+    - was_successful: Boolean parameter indicating success/failure
+    - result_details: String parameter with operation details
+
+    The component can be customized for different parameter modes to support
+    various node types (EndNode uses INPUT/PROPERTY, SuccessFailureNode uses OUTPUT).
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        node: Any,  # BaseNode type, but avoiding circular import
+        *,
+        was_successful_modes: set[ParameterMode],
+        result_details_modes: set[ParameterMode],
+        parameter_group_initially_collapsed: bool = True,
+        result_details_tooltip: str = "Details about the operation result",
+        result_details_placeholder: str = "Details on the operation will be presented here.",
+    ) -> None:
+        """Initialize the ExecutionStatusComponent and create the parameters immediately.
+
+        Args:
+            node: The node instance that will own these parameters
+            was_successful_modes: Set of ParameterModes for was_successful parameter
+            result_details_modes: Set of ParameterModes for result_details parameter
+            parameter_group_initially_collapsed: Whether the Status group should start collapsed
+            result_details_tooltip: Custom tooltip for result_details parameter
+            result_details_placeholder: Custom placeholder text for result_details parameter
+        """
+        self._node = node
+
+        # Create the Status ParameterGroup
+        self._status_group = ParameterGroup(name="Status")
+        self._status_group.ui_options = {"collapsed": parameter_group_initially_collapsed}
+
+        # Boolean parameter to indicate success/failure
+        self._was_successful = Parameter(
+            name="was_successful",
+            tooltip="Indicates whether it completed without errors.",
+            type="bool",
+            default_value=False,
+            settable=False,
+            allowed_modes=was_successful_modes,
+        )
+
+        # Result details parameter with multiline option
+        self._result_details = Parameter(
+            name="result_details",
+            tooltip=result_details_tooltip,
+            type="str",
+            default_value=None,
+            allowed_modes=result_details_modes,
+            settable=False,
+            ui_options={
+                "multiline": True,
+                "placeholder_text": result_details_placeholder,
+            },
+        )
+
+        # Add parameters to the group
+        self._status_group.add_child(self._was_successful)
+        self._status_group.add_child(self._result_details)
+
+        # Add the group to the node
+        self._node.add_node_element(self._status_group)
+
+    def get_parameter_group(self) -> ParameterGroup:
+        """Get the Status ParameterGroup.
+
+        Returns:
+            ParameterGroup: The Status group containing was_successful and result_details
+        """
+        return self._status_group
+
+    def set_execution_result(self, *, was_successful: bool, result_details: str) -> None:
+        """Set the execution result values.
+
+        Args:
+            was_successful: Whether the operation succeeded
+            result_details: Details about the operation result
+        """
+        self._update_parameter_value(self._was_successful, was_successful)
+        self._update_parameter_value(self._result_details, result_details)
+
+    def clear_execution_status(self, initial_message: str | None = None) -> None:
+        """Clear execution status and reset parameters.
+
+        Args:
+            initial_message: Initial message to set in result_details. If None, clears result_details entirely.
+        """
+        if initial_message is None:
+            initial_message = ""
+        self.set_execution_result(was_successful=False, result_details=initial_message)
+
+    def append_to_result_details(self, additional_text: str, separator: str = "\n") -> None:
+        """Append text to the existing result_details.
+
+        Args:
+            additional_text: Text to append to the current result_details
+            separator: Separator to use between existing and new text (default: newline)
+        """
+        # Get current result_details value
+        current_details = self._node.get_parameter_value(self._result_details.name)
+
+        # Append the new text
+        if current_details:
+            updated_details = f"{current_details}{separator}{additional_text}"
+        else:
+            updated_details = additional_text
+
+        # Use consolidated update method
+        self._update_parameter_value(self._result_details, updated_details)
+
+    def _update_parameter_value(self, parameter: Parameter, value: Any) -> None:
+        """Update a parameter value with all necessary operations.
+
+        Args:
+            parameter: The parameter to update
+            value: The new value to set
+        """
+        # ALWAYS set parameter value and publish update
+        self._node.set_parameter_value(parameter.name, value)
+        self._node.publish_update_to_parameter(parameter.name, value)
+
+        # ONLY set output values if the parameter mode is OUTPUT
+        if ParameterMode.OUTPUT in parameter.get_mode():
+            self._node.parameter_output_values[parameter.name] = value