griptape-nodes 0.49.0__py3-none-any.whl → 0.51.0__py3-none-any.whl

griptape_nodes/exe_types/core_types.py

@@ -714,6 +714,10 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
     # During save/load, this value IS still serialized to save its proper state.
     settable: bool = True
 
+    # "serializable" controls whether parameter values should be serialized during save/load operations.
+    # Set to False for parameters containing non-serializable types (ImageDrivers, PromptDrivers, file handles, etc.)
+    serializable: bool = True
+
     user_defined: bool = False
     _allowed_modes: set = field(
         default_factory=lambda: {
@@ -747,6 +751,7 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         ui_options: dict | None = None,
         *,
         settable: bool = True,
+        serializable: bool = True,
         user_defined: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
@@ -764,6 +769,7 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         self.tooltip_as_property = tooltip_as_property
         self.tooltip_as_output = tooltip_as_output
         self.settable = settable
+        self.serializable = serializable
         self.user_defined = user_defined
         if allowed_modes is None:
             self._allowed_modes = {ParameterMode.INPUT, ParameterMode.OUTPUT, ParameterMode.PROPERTY}
@@ -813,6 +819,8 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         our_dict["tooltip_as_property"] = self.tooltip_as_property
 
         our_dict["is_user_defined"] = self.user_defined
+        our_dict["settable"] = self.settable
+        our_dict["serializable"] = self.serializable
         our_dict["ui_options"] = self.ui_options
 
         # Let's bundle up the mode details.

griptape_nodes/exe_types/node_types.py

@@ -4,7 +4,7 @@ import logging
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Generator, Iterable
 from enum import StrEnum, auto
-from typing import Any, TypeVar
+from typing import Any, NamedTuple, TypeVar
 
 from griptape.events import BaseEvent, EventBus
 
@@ -26,12 +26,14 @@ from griptape_nodes.retained_mode.events.base_events import (
     ExecutionEvent,
     ExecutionGriptapeNodeEvent,
     ProgressEvent,
+    RequestPayload,
 )
 from griptape_nodes.retained_mode.events.execution_events import (
     NodeUnresolvedEvent,
     ParameterValueUpdateEvent,
 )
 from griptape_nodes.retained_mode.events.parameter_events import (
+    AddParameterToNodeRequest,
     RemoveElementEvent,
     RemoveParameterFromNodeRequest,
 )
@@ -52,6 +54,23 @@ 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
@@ -148,6 +167,15 @@ class BaseNode(ABC):
         """Callback to confirm allowing a Connection going OUT of this Node."""
         return True
 
+    def before_incoming_connection(
+        self,
+        source_node: BaseNode,  # noqa: ARG002
+        source_parameter_name: str,  # noqa: ARG002
+        target_parameter_name: str,  # noqa: ARG002
+    ) -> None:
+        """Callback before validating a Connection coming TO this Node."""
+        return
+
     def after_incoming_connection(
         self,
         source_node: BaseNode,  # noqa: ARG002
@@ -157,6 +185,15 @@ class BaseNode(ABC):
         """Callback after a Connection has been established TO this Node."""
         return
 
+    def before_outgoing_connection(
+        self,
+        source_parameter_name: str,  # noqa: ARG002
+        target_node: BaseNode,  # noqa: ARG002
+        target_parameter_name: str,  # noqa: ARG002
+    ) -> None:
+        """Callback before validating a Connection going OUT of this Node."""
+        return
+
     def after_outgoing_connection(
         self,
         source_parameter: Parameter,  # noqa: ARG002
@@ -251,6 +288,31 @@ class BaseNode(ABC):
         """Callback for when a Griptape Event comes destined for this Node."""
         return
 
+    def on_node_message_received(
+        self,
+        optional_element_name: str | None,  # noqa: ARG002
+        message_type: str,
+        message: Any,  # noqa: ARG002
+    ) -> 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.
+
+        Args:
+            optional_element_name: Optional element name this message relates to
+            message_type: String indicating the message type for parsing
+            message: Message payload of any type
+
+        Returns:
+            NodeMessageResult: Result containing success status, details, and optional response
+        """
+        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.",
+            response=None,
+        )
+
     def does_name_exist(self, param_name: str) -> bool:
         for parameter in self.parameters:
             if parameter.name == param_name:
@@ -1070,6 +1132,218 @@ class EndLoopNode(BaseNode):
     """Creating class for Start Loop Node in order to implement loop functionality in execution."""
 
 
+class ErrorProxyNode(BaseNode):
+    """A proxy node that substitutes for nodes that failed to create due to missing dependencies or errors.
+
+    This node maintains the original node type information and allows workflows to continue loading
+    even when some node types are unavailable. It generates parameters dynamically as connections
+    and values are assigned to maintain workflow structure.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        original_node_type: str,
+        original_library_name: str,
+        failure_reason: str,
+        metadata: dict[Any, Any] | None = None,
+    ) -> None:
+        super().__init__(name, metadata)
+
+        self.original_node_type = original_node_type
+        self.original_library_name = original_library_name
+        self.failure_reason = failure_reason
+        # Record ALL initial_setup=True requests in order for 1:1 replay
+        self._recorded_initialization_requests: list[RequestPayload] = []
+
+        # Track if user has made connection modifications after initial setup
+        self._has_connection_modifications: bool = False
+
+        # Add error message parameter explaining the failure
+        self._error_message = ParameterMessage(
+            name="error_proxy_message",
+            variant="error",
+            value="",  # Will be set by _update_error_message
+        )
+        self.add_node_element(self._error_message)
+        self._update_error_message()
+
+    def _get_base_error_message(self) -> str:
+        """Generate the base error message for this ErrorProxyNode."""
+        return (
+            f"This is a placeholder for a node of type '{self.original_node_type}'"
+            f"\nfrom the '{self.original_library_name}' library."
+            f"\nIt encountered a problem when loading."
+            f"\nThe technical issue:\n{self.failure_reason}\n\n"
+            f"Your original node will be restored once the issue above is fixed "
+            f"(which may require registering the appropriate library, or getting "
+            f"a code fix from the node author)."
+        )
+
+    def on_attempt_set_parameter_value(self, param_name: str) -> None:
+        """Public method to attempt setting a parameter value during initial setup.
+
+        Creates a PROPERTY mode parameter if it doesn't exist to support value setting.
+
+        Args:
+            param_name: Name of the parameter to prepare for value setting
+        """
+        self._ensure_parameter_exists(param_name)
+
+    def _ensure_parameter_exists(self, param_name: str) -> None:
+        """Ensures a parameter exists on this node.
+
+        Creates a universal parameter with all modes enabled for maximum flexibility.
+        Auto-generated parameters are marked as non-user-defined so they don't get serialized.
+
+        Args:
+            param_name: Name of the parameter to ensure exists
+        """
+        existing_param = super().get_parameter_by_name(param_name)
+
+        if existing_param is None:
+            # Create new universal parameter with all modes enabled
+            from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+
+            request = AddParameterToNodeRequest(
+                node_name=self.name,
+                parameter_name=param_name,
+                type=ParameterTypeBuiltin.ANY.value,  # ANY = parameter's main type for maximum flexibility
+                input_types=[ParameterTypeBuiltin.ANY.value],  # ANY = accepts any single input type
+                output_type=ParameterTypeBuiltin.ALL.value,  # ALL = can output any type (passthrough)
+                tooltip="Parameter created for placeholder node to preserve workflow connections",
+                mode_allowed_input=True,  # Enable all modes upfront
+                mode_allowed_output=True,
+                mode_allowed_property=True,
+                is_user_defined=False,  # Don't serialize this parameter
+                initial_setup=True,  # Allows setting non-settable parameters and prevents resolution cascades during workflow loading
+            )
+            result = GriptapeNodes.handle_request(request)
+
+            # Check if parameter creation was successful
+            from griptape_nodes.retained_mode.events.parameter_events import AddParameterToNodeResultSuccess
+
+            if not isinstance(result, AddParameterToNodeResultSuccess):
+                failure_message = f"Failed to create parameter '{param_name}': {result.result_details}"
+                raise RuntimeError(failure_message)
+        # If parameter already exists, nothing to do - it already has all modes
+
+    def allow_incoming_connection(
+        self,
+        source_node: BaseNode,  # noqa: ARG002
+        source_parameter: Parameter,  # noqa: ARG002
+        target_parameter: Parameter,  # noqa: ARG002
+    ) -> bool:
+        """ErrorProxyNode allows connections - it's a shell for maintaining connections."""
+        return True
+
+    def allow_outgoing_connection(
+        self,
+        source_parameter: Parameter,  # noqa: ARG002
+        target_node: BaseNode,  # noqa: ARG002
+        target_parameter: Parameter,  # noqa: ARG002
+    ) -> bool:
+        """ErrorProxyNode allows connections - it's a shell for maintaining connections."""
+        return True
+
+    def before_incoming_connection(
+        self,
+        source_node: BaseNode,  # noqa: ARG002
+        source_parameter_name: str,  # noqa: ARG002
+        target_parameter_name: str,
+    ) -> None:
+        """Create target parameter before connection validation."""
+        self._ensure_parameter_exists(target_parameter_name)
+
+    def before_outgoing_connection(
+        self,
+        source_parameter_name: str,
+        target_node: BaseNode,  # noqa: ARG002
+        target_parameter_name: str,  # noqa: ARG002
+    ) -> None:
+        """Create source parameter before connection validation."""
+        self._ensure_parameter_exists(source_parameter_name)
+
+    def set_post_init_connections_modified(self) -> None:
+        """Mark that user-initiated connections have been modified and update the warning message."""
+        if not self._has_connection_modifications:
+            self._has_connection_modifications = True
+            self._update_error_message()
+
+    def _update_error_message(self) -> None:
+        """Update the ParameterMessage to include connection modification warning."""
+        # Build the updated message with connection warning
+        base_message = self._get_base_error_message()
+
+        # Add connection modification warning if applicable
+        if self._has_connection_modifications:
+            connection_warning = (
+                "\n\nWARNING: You have modified connections to this placeholder node."
+                "\nThis may require manual fixes when the original node is restored."
+            )
+            final_message = base_message + connection_warning
+        else:
+            # Add the general note only if no modifications have been made
+            general_warning = (
+                "\n\nNote: Making changes to this node may require manual fixes when restored,"
+                "\nas we can't predict how all node authors craft their custom nodes."
+            )
+            final_message = base_message + general_warning
+
+        # Update the error message value
+        self._error_message.value = final_message
+
+    def validate_before_node_run(self) -> list[Exception] | None:
+        """Prevent ErrorProxy nodes from running - validate at node level only."""
+        error_msg = (
+            f"Cannot run node '{self.name}': This is a placeholder node put in place to preserve your workflow until the breaking issue is fixed.\n\n"
+            f"The original '{self.original_node_type}' from library '{self.original_library_name}' failed to load due to this technical issue:\n\n"
+            f"{self.failure_reason}\n\n"
+            f"Once you resolve the issue above, reload this workflow and the placeholder will be automatically replaced with the original node."
+        )
+        return [RuntimeError(error_msg)]
+
+    def record_initialization_request(self, request: RequestPayload) -> None:
+        """Record an initialization request for replay during serialization.
+
+        This method captures requests that modify ErrorProxyNode structure during workflow loading,
+        preserving information needed for restoration when the original node becomes available.
+
+        WHAT WE RECORD:
+        - AlterParameterDetailsRequest: Parameter modifications from original node definition
+        - Any request with initial_setup=True that changes node structure in ways that cannot
+          be reconstructed from final state alone
+
+        WHAT WE DO NOT RECORD (and why):
+        - SetParameterValueRequest: Final parameter values are serialized normally via parameter_values
+        - AddParameterToNodeRequest: User-defined parameters are serialized via is_user_defined=True flag
+        - CreateConnectionRequest: Connections are serialized separately and recreated during loading
+        - RenameParameterRequest: Final parameter names are preserved in serialized state
+        - SetNodeMetadataRequest: Final metadata state is preserved in node.metadata
+        - SetLockNodeStateRequest: Final lock state is preserved in node.lock
+        """
+        self._recorded_initialization_requests.append(request)
+
+    def get_recorded_initialization_requests(self, request_type: type | None = None) -> list[RequestPayload]:
+        """Get recorded initialization requests for 1:1 serialization replay.
+
+        Args:
+            request_type: Optional class to filter by. If provided, only returns requests
+                         of that type. If None, returns all recorded requests.
+
+        Returns:
+            List of recorded requests in the order they were received.
+        """
+        if request_type is None:
+            return self._recorded_initialization_requests
+
+        return [req for req in self._recorded_initialization_requests if isinstance(req, request_type)]
+
+    def process(self) -> Any:
+        """No-op process method. Error Proxy nodes do nothing during execution."""
+        return None
+
+
 class Connection:
     source_node: BaseNode
     target_node: BaseNode

griptape_nodes/retained_mode/events/node_events.py

@@ -45,6 +45,7 @@ class CreateNodeRequest(RequestPayload):
         resolution: Initial resolution state (defaults to UNRESOLVED)
         initial_setup: Skip setup work when loading from file (defaults to False)
         set_as_new_context: Set this node as current context after creation (defaults to False)
+        create_error_proxy_on_failure: Create Error Proxy node if creation fails (defaults to True)
 
     Results: CreateNodeResultSuccess (with assigned name) | CreateNodeResultFailure (invalid type, missing library, flow not found)
     """
@@ -60,6 +61,8 @@ class CreateNodeRequest(RequestPayload):
     initial_setup: bool = False
     # When True, this Node will be pushed as the current Node within the Current Context.
     set_as_new_context: bool = False
+    # When True, create an Error Proxy node if the requested node type fails to create
+    create_error_proxy_on_failure: bool = True
 
 
 @dataclass
@@ -262,6 +265,50 @@ class SetNodeMetadataResultFailure(ResultPayloadFailure):
     """Metadata update failed. Common causes: node not found, no current context, invalid metadata format."""
 
 
+@dataclass
+@PayloadRegistry.register
+class BatchSetNodeMetadataRequest(RequestPayload):
+    """Update metadata for multiple nodes in a single request.
+
+    Use when: Updating positions for multiple nodes at once, applying bulk styling changes,
+    implementing multi-node selection operations, optimizing performance for UI updates.
+    Supports partial updates - only specified metadata fields are updated for each node.
+
+    Args:
+        node_metadata_updates: Dictionary mapping node names to their metadata updates.
+                              Each node's metadata is merged with existing metadata (partial update).
+                              If a node name is None, uses the current context node.
+
+    Results: BatchSetNodeMetadataResultSuccess | BatchSetNodeMetadataResultFailure (some nodes not found, update errors)
+    """
+
+    node_metadata_updates: dict[str | None, dict[str, Any]]
+
+
+@dataclass
+@PayloadRegistry.register
+class BatchSetNodeMetadataResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Batch node metadata update completed successfully.
+
+    Args:
+        updated_nodes: List of node names that were successfully updated
+        failed_nodes: Dictionary mapping failed node names to error descriptions (if any)
+    """
+
+    updated_nodes: list[str]
+    failed_nodes: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+@PayloadRegistry.register
+class BatchSetNodeMetadataResultFailure(ResultPayloadFailure):
+    """Batch metadata update failed.
+
+    Common causes: all nodes not found, no current context, invalid metadata format,
+    or other systemic errors preventing the batch operation.
+    """
+
+
 # Get all info via a "jumbo" node event. Batches multiple info requests for, say, a GUI.
 # ...jumbode?
 @dataclass
@@ -677,3 +724,53 @@ class DuplicateSelectedNodesResultFailure(WorkflowNotAlteredMixin, ResultPayload
     Common causes: nodes not found, constraints/conflicts,
     insufficient resources, connection duplication failures.
     """
+
+
+@dataclass
+@PayloadRegistry.register
+class SendNodeMessageRequest(RequestPayload):
+    """Send a message to a specific node.
+
+    Use when: External systems need to signal or send data directly to individual nodes,
+    implementing custom communication patterns, triggering node-specific behaviors.
+
+    Args:
+        node_name: Name of the target node (None for current context node)
+        optional_element_name: Optional element name this message relates to
+        message_type: String indicating message type for receiver parsing
+        message: Message payload of any type
+
+    Results: SendNodeMessageResultSuccess (with response) | SendNodeMessageResultFailure (node not found, handler error)
+    """
+
+    message_type: str
+    message: Any
+    node_name: str | None = None
+    optional_element_name: str | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class SendNodeMessageResultSuccess(ResultPayloadSuccess):
+    """Node message sent and processed successfully.
+
+    Args:
+        response: Optional response data from the node's message handler
+    """
+
+    response: Any = None
+
+
+@dataclass
+@PayloadRegistry.register
+class SendNodeMessageResultFailure(ResultPayloadFailure):
+    """Node message sending failed.
+
+    Common causes: node not found, no current context, message handler error,
+    unsupported message type.
+
+    Args:
+        response: Optional response data from the node's message handler (even on failure)
+    """
+
+    response: Any = None

griptape_nodes/retained_mode/events/parameter_events.py

@@ -40,6 +40,7 @@ class AddParameterToNodeRequest(RequestPayload):
         mode_allowed_input: Whether parameter can be used as input
         mode_allowed_property: Whether parameter can be used as property
         mode_allowed_output: Whether parameter can be used as output
+        is_user_defined: Whether this is a user-defined parameter (affects serialization)
         parent_container_name: Name of parent container if nested
         initial_setup: Skip setup work when loading from file
 
@@ -61,6 +62,7 @@ class AddParameterToNodeRequest(RequestPayload):
     mode_allowed_input: bool = Field(default=True)
     mode_allowed_property: bool = Field(default=True)
     mode_allowed_output: bool = Field(default=True)
+    is_user_defined: bool = Field(default=True)
     parent_container_name: str | None = None
     # initial_setup prevents unnecessary work when we are loading a workflow from a file.
     initial_setup: bool = False

griptape_nodes/retained_mode/managers/flow_manager.py

@@ -14,7 +14,7 @@ from griptape_nodes.exe_types.core_types import (
     ParameterTypeBuiltin,
 )
 from griptape_nodes.exe_types.flow import ControlFlow
-from griptape_nodes.exe_types.node_types import BaseNode, NodeResolutionState, StartLoopNode, StartNode
+from griptape_nodes.exe_types.node_types import BaseNode, ErrorProxyNode, NodeResolutionState, StartLoopNode, StartNode
 from griptape_nodes.machines.control_flow import CompleteState, ControlFlowMachine
 from griptape_nodes.retained_mode.events.base_events import (
     ExecutionEvent,
@@ -681,6 +681,18 @@ class FlowManager:
 
         # Cross-flow connections are now supported via global connection storage
 
+        # Call before_connection callbacks to allow nodes to prepare parameters
+        source_node.before_outgoing_connection(
+            source_parameter_name=request.source_parameter_name,
+            target_node=target_node,
+            target_parameter_name=request.target_parameter_name,
+        )
+        target_node.before_incoming_connection(
+            source_node=source_node,
+            source_parameter_name=request.source_parameter_name,
+            target_parameter_name=request.target_parameter_name,
+        )
+
         # Now validate the parameters.
         source_param = source_node.get_parameter_by_name(request.source_parameter_name)
         if source_param is None:
@@ -852,6 +864,13 @@ class FlowManager:
                 )
             )
 
+        # Check if either node is ErrorProxyNode and mark connection modification if not initial_setup
+        if not request.initial_setup:
+            if isinstance(source_node, ErrorProxyNode):
+                source_node.set_post_init_connections_modified()
+            if isinstance(target_node, ErrorProxyNode):
+                target_node.set_post_init_connections_modified()
+
         result = CreateConnectionResultSuccess()
 
         return result
@@ -995,6 +1014,12 @@ class FlowManager:
         details = f'Connection "{source_node_name}.{request.source_parameter_name}" to "{target_node_name}.{request.target_parameter_name}" deleted.'
         logger.debug(details)
 
+        # Check if either node is ErrorProxyNode and mark connection modification (deletes are always user-initiated)
+        if isinstance(source_node, ErrorProxyNode):
+            source_node.set_post_init_connections_modified()
+        if isinstance(target_node, ErrorProxyNode):
+            target_node.set_post_init_connections_modified()
+
         result = DeleteConnectionResultSuccess()
         return result
 
@@ -1880,6 +1905,7 @@ class FlowManager:
         valid_data_nodes = []
         start_nodes = []
         control_nodes = []
+        cn_mgr = self.get_connections()
         for node in all_nodes:
             # if it's a start node, start here! Return the first one!
             if isinstance(node, StartNode):
@@ -1890,15 +1916,21 @@ class FlowManager:
             control_param = False
             for parameter in node.parameters:
                 if ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
-                    control_param = True
-                    break
+                    # Check if the control parameters are being used at all. If they are not, treat it as a data node.
+                    incoming_control = (
+                        node.name in cn_mgr.incoming_index and parameter.name in cn_mgr.incoming_index[node.name]
+                    )
+                    outgoing_control = (
+                        node.name in cn_mgr.outgoing_index and parameter.name in cn_mgr.outgoing_index[node.name]
+                    )
+                    if incoming_control or outgoing_control:
+                        control_param = True
+                        break
             if not control_param:
                 # saving this for later
                 data_nodes.append(node)
                 # If this node doesn't have a control connection..
                 continue
-
-            cn_mgr = self.get_connections()
             # check if it has an incoming connection. If it does, it's not a start node
             has_control_connection = False
             if node.name in cn_mgr.incoming_index:
@@ -1906,10 +1938,19 @@ class FlowManager:
                     param = node.get_parameter_by_name(param_name)
                     if param and ParameterTypeBuiltin.CONTROL_TYPE.value == param.output_type:
                         # there is a control connection coming in
+                        # If the node is a StartLoopNode, it may have an incoming hidden connection from it's EndLoopNode for iteration.
+                        if isinstance(node, StartLoopNode):
+                            connection_id = cn_mgr.incoming_index[node.name][param_name][0]
+                            connection = cn_mgr.connections[connection_id]
+                            connected_node = connection.get_source_node()
+                            # Check if the source node is the end loop node associated with this StartLoopNode.
+                            # If it is, then this could still be the first node in the control flow.
+                            if connected_node == node.end_node:
+                                continue
                         has_control_connection = True
                         break
             # if there is a connection coming in, isn't a start.
-            if has_control_connection and not isinstance(node, StartLoopNode):
+            if has_control_connection:
                 continue
             # Does it have an outgoing connection?
             if node.name in cn_mgr.outgoing_index: