griptape-nodes 0.63.9__tar.gz → 0.64.0__tar.gz

{griptape_nodes-0.63.9 → griptape_nodes-0.64.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: griptape-nodes
-Version: 0.63.9
+Version: 0.64.0
 Summary: Add your description here
 Requires-Dist: griptape>=1.8.12
 Requires-Dist: pydantic>=2.10.6
@@ -27,6 +27,7 @@ Requires-Dist: aiofiles>=25.1.0
 Requires-Dist: aioshutil>=1.5
 Requires-Dist: ruamel-yaml>=0.18.15
 Requires-Dist: asyncio-thread-runner>=1.0
+Requires-Dist: portalocker>=2.10.0
 Requires-Dist: austin-dist>=3.7.0 ; extra == 'profiling'
 Requires-Python: >=3.12.0, <3.13
 Provides-Extra: profiling
@@ -55,6 +56,7 @@ This repository contains the Griptape Nodes Engine - the local component that ru
 - **📚 Full Documentation:** [docs.griptapenodes.com](https://docs.griptapenodes.com)
 - **⚙️ Installation:** [docs.griptapenodes.com/en/stable/installation/](https://docs.griptapenodes.com/en/latest/installation/)
 - **🔧 Engine Configuration:** [docs.griptapenodes.com/en/stable/configuration/](https://docs.griptapenodes.com/en/latest/configuration/)
+- **📋 Migration Guide:** [MIGRATION.md](MIGRATION.md) - Guide for migrating from deprecated nodes
 
 **🧩 Extending Griptape Nodes:**
 

{griptape_nodes-0.63.9 → griptape_nodes-0.64.0}/README.md

@@ -21,6 +21,7 @@ This repository contains the Griptape Nodes Engine - the local component that ru
 - **📚 Full Documentation:** [docs.griptapenodes.com](https://docs.griptapenodes.com)
 - **⚙️ Installation:** [docs.griptapenodes.com/en/stable/installation/](https://docs.griptapenodes.com/en/latest/installation/)
 - **🔧 Engine Configuration:** [docs.griptapenodes.com/en/stable/configuration/](https://docs.griptapenodes.com/en/latest/configuration/)
+- **📋 Migration Guide:** [MIGRATION.md](MIGRATION.md) - Guide for migrating from deprecated nodes
 
 **🧩 Extending Griptape Nodes:**
 

{griptape_nodes-0.63.9 → griptape_nodes-0.64.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "griptape-nodes"
-version = "0.63.9"
+version = "0.64.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12.0, <3.13"
@@ -31,6 +31,7 @@ dependencies = [
   "aioshutil>=1.5",
   "ruamel.yaml>=0.18.15",
   "asyncio-thread-runner>=1.0",
+  "portalocker>=2.10.0",
 ]
 
 [project.optional-dependencies]

{griptape_nodes-0.63.9 → griptape_nodes-0.64.0}/src/griptape_nodes/common/node_executor.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import ast
 import logging
 import pickle
+from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, NamedTuple
 
@@ -15,8 +16,7 @@ from griptape_nodes.exe_types.node_types import (
     PRIVATE_EXECUTION,
     BaseNode,
     EndNode,
-    NodeGroup,
-    NodeGroupProxyNode,
+    NodeGroupNode,
     StartNode,
 )
 from griptape_nodes.node_library.library_registry import Library, LibraryRegistry
@@ -30,6 +30,7 @@ from griptape_nodes.retained_mode.events.workflow_events import (
     DeleteWorkflowResultFailure,
     LoadWorkflowMetadata,
     LoadWorkflowMetadataResultSuccess,
+    PublishWorkflowRegisteredEventData,
     PublishWorkflowRequest,
     SaveWorkflowFileFromSerializedFlowRequest,
     SaveWorkflowFileFromSerializedFlowResultSuccess,
@@ -37,13 +38,20 @@ from griptape_nodes.retained_mode.events.workflow_events import (
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
 if TYPE_CHECKING:
-    from griptape_nodes.exe_types.connections import Connections
     from griptape_nodes.retained_mode.events.node_events import SerializedNodeCommands
     from griptape_nodes.retained_mode.managers.library_manager import LibraryManager
 
 logger = logging.getLogger("griptape_nodes")
 
 
+@dataclass
+class PublishWorkflowStartEndNodes:
+    start_flow_node_type: str
+    start_flow_node_library_name: str
+    end_flow_node_type: str
+    end_flow_node_library_name: str
+
+
 class PublishLocalWorkflowResult(NamedTuple):
     """Result from publishing a local workflow."""
 
@@ -72,14 +80,21 @@ class NodeExecutor:
             node: The BaseNode to execute
             library_name: The library that the execute method should come from.
         """
-        execution_type = node.get_parameter_value(node.execution_environment.name)
-
-        if execution_type == LOCAL_EXECUTION:
-            await node.aprocess()
-        elif execution_type == PRIVATE_EXECUTION:
-            await self._execute_private_workflow(node)
-        else:
+        if isinstance(node, NodeGroupNode):
+            execution_type = node.get_parameter_value(node.execution_environment.name)
+            if execution_type == LOCAL_EXECUTION:
+                # Just execute the node normally! This means we aren't doing any special packaging.
+                await node.aprocess()
+                return
+            if execution_type == PRIVATE_EXECUTION:
+                # Package the flow and run it in a subprocess.
+                await self._execute_private_workflow(node)
+                return
+            # If it isn't Local or Private, it must be a library name. We'll try to execute it, and if the library name doesn't exist, it'll raise an error.
             await self._execute_library_workflow(node, execution_type)
+            return
+        # We default to local execution if it is not a NodeGroupNode!
+        await node.aprocess()
 
     async def _execute_and_apply_workflow(
         self,
@@ -109,6 +124,9 @@ class NodeExecutor:
         workflow_result = None
         try:
             result = await self._publish_local_workflow(node)
+            if result is None:
+                # Length of list is 0, no node names in group.
+                return
             workflow_result = result.workflow_result
         except Exception as e:
             logger.exception(
@@ -169,6 +187,9 @@ class NodeExecutor:
 
         try:
             result = await self._publish_local_workflow(node, library=library)
+            if result is None:
+                # Length of list is 0, no node names in group.
+                return
             workflow_result = result.workflow_result
         except Exception as e:
             logger.exception(
@@ -221,47 +242,74 @@ class NodeExecutor:
                 published_filename = published_workflow_filename.stem
                 await self._delete_workflow(workflow_name=published_filename, workflow_path=published_workflow_filename)
 
-    async def _publish_local_workflow(
-        self, node: BaseNode, library: Library | None = None
-    ) -> PublishLocalWorkflowResult:
-        """Package and publish a workflow for subprocess execution.
-
-        Returns:
-            PublishLocalWorkflowResult containing workflow_result, file_name, and output_parameter_prefix
-        """
-        sanitized_node_name = node.name.replace(" ", "_")
-        output_parameter_prefix = f"{sanitized_node_name}_packaged_node_"
-        # We have to make our defaults strings because the PackageNodesAsSerializedFlowRequest doesn't accept None types.
+    async def _get_workflow_start_end_nodes(self, library: Library | None) -> PublishWorkflowStartEndNodes:
         library_name = "Griptape Nodes Library"
         start_node_type = "StartFlow"
         end_node_type = "EndFlow"
+
         if library is not None:
+            # Attempt to get start and end nodes from the registered handler
+            library_name = library.get_library_data().name
+            registered_event_handler = self.get_workflow_handler(library_name)
+            registered_event_data = registered_event_handler.event_data
+            if registered_event_data is not None and isinstance(
+                registered_event_data, PublishWorkflowRegisteredEventData
+            ):
+                return PublishWorkflowStartEndNodes(
+                    start_flow_node_type=registered_event_data.start_flow_node_type,
+                    start_flow_node_library_name=registered_event_data.start_flow_node_library_name,
+                    end_flow_node_type=registered_event_data.end_flow_node_type,
+                    end_flow_node_library_name=registered_event_data.end_flow_node_library_name,
+                )
+
             start_nodes = library.get_nodes_by_base_type(StartNode)
             end_nodes = library.get_nodes_by_base_type(EndNode)
             if len(start_nodes) > 0 and len(end_nodes) > 0:
                 start_node_type = start_nodes[0]
                 end_node_type = end_nodes[0]
                 library_name = library.get_library_data().name
+
+        return PublishWorkflowStartEndNodes(
+            start_flow_node_type=start_node_type,
+            start_flow_node_library_name=library_name,
+            end_flow_node_type=end_node_type,
+            end_flow_node_library_name=library_name,
+        )
+
+    async def _publish_local_workflow(
+        self, node: BaseNode, library: Library | None = None
+    ) -> PublishLocalWorkflowResult | None:
+        """Package and publish a workflow for subprocess execution.
+
+        Returns:
+            PublishLocalWorkflowResult containing workflow_result, file_name, and output_parameter_prefix
+        """
+        sanitized_node_name = node.name.replace(" ", "_")
+        output_parameter_prefix = f"{sanitized_node_name}_packaged_node_"
+        # We have to make our defaults strings because the PackageNodesAsSerializedFlowRequest doesn't accept None types.
+        library_name = library.get_library_data().name if library is not None else "Griptape Nodes Library"
+        workflow_start_end_nodes = await self._get_workflow_start_end_nodes(library)
+
         sanitized_library_name = library_name.replace(" ", "_")
-        # If we are packaging a NodeGroupProxyNode, that means that we are packaging multiple nodes together, so we have to get the list of nodes from the proxy node.
-        if isinstance(node, NodeGroupProxyNode):
-            node_names = list(node.node_group_data.nodes.keys())
+        # If we are packaging a NodeGroupNode, that means that we are packaging multiple nodes together, so we have to get the list of nodes from the group node.
+        if isinstance(node, NodeGroupNode):
+            node_names = list(node.get_all_nodes().keys())
         else:
             # Otherwise, it's a list of one node!
             node_names = [node.name]
 
-        # Pass the proxy node if this is a NodeGroupProxyNode so serialization can use stored connections
-        proxy_node_for_packaging = node if isinstance(node, NodeGroupProxyNode) else None
+        if len(node_names) == 0:
+            return None
 
         request = PackageNodesAsSerializedFlowRequest(
             node_names=node_names,
-            start_node_type=start_node_type,
-            end_node_type=end_node_type,
-            start_end_specific_library_name=library_name,
+            start_node_type=workflow_start_end_nodes.start_flow_node_type,
+            end_node_type=workflow_start_end_nodes.end_flow_node_type,
+            start_node_library_name=workflow_start_end_nodes.start_flow_node_library_name,
+            end_node_library_name=workflow_start_end_nodes.end_flow_node_library_name,
             output_parameter_prefix=output_parameter_prefix,
             entry_control_node_name=None,
             entry_control_parameter_name=None,
-            proxy_node=proxy_node_for_packaging,
         )
         package_result = GriptapeNodes.handle_request(request)
         if not isinstance(package_result, PackageNodesAsSerializedFlowResultSuccess):
@@ -420,7 +468,7 @@ class NodeExecutor:
             return stored_value
         return stored_value
 
-    def _apply_parameter_values_to_node(  # noqa: C901
+    def _apply_parameter_values_to_node(
         self,
         node: BaseNode,
         parameter_output_values: dict[str, Any],
@@ -430,7 +478,7 @@ class NodeExecutor:
 
         Sets parameter values on the node and updates parameter_output_values dictionary.
         Uses parameter_name_mappings from package_result to map packaged parameters back to original nodes.
-        Works for both single-node and multi-node packages.
+        Works for both single-node and multi-node packages (NodeGroupNode).
         """
         # If the packaged flow fails, the End Flow Node in the library published workflow will have entered from 'failed'
         if "failed" in parameter_output_values and parameter_output_values["failed"] == CONTROL_INPUT_PARAMETER:
@@ -448,26 +496,26 @@ class NodeExecutor:
             target_node_name = original_node_param.node_name
             target_param_name = original_node_param.parameter_name
 
-            # For multi-node packages, get the target node from the group
-            # For single-node packages, use the node itself
-            if isinstance(node, NodeGroupProxyNode):
-                if target_node_name not in node.node_group_data.nodes:
-                    msg = f"Target node '{target_node_name}' not found in node group for proxy node '{node.name}'. Available nodes: {list(node.node_group_data.nodes.keys())}"
-                    raise RuntimeError(msg)
-                target_node = node.node_group_data.nodes[target_node_name]
+            # Determine the target node - if this is a NodeGroupNode, look up the child node
+            if isinstance(node, NodeGroupNode):
+                if target_node_name not in node.nodes:
+                    logger.warning(
+                        "Node '%s' not found in NodeGroupNode '%s', skipping value application",
+                        target_node_name,
+                        node.name,
+                    )
+                    continue
+                target_node = node.nodes[target_node_name]
             else:
                 target_node = node
 
             # Get the parameter from the target node
             target_param = target_node.get_parameter_by_name(target_param_name)
-
-            # Skip if parameter not found or is special parameter (execution_environment, node_group)
-            if target_param is None or target_param in (
-                target_node.execution_environment,
-                target_node.node_group,
-            ):
-                logger.debug(
-                    "Skipping special or missing parameter '%s' on node '%s'", target_param_name, target_node_name
+            if target_param is None:
+                logger.warning(
+                    "Parameter '%s' not found on node '%s', skipping value application",
+                    target_param_name,
+                    target_node_name,
                 )
                 continue
 
@@ -476,16 +524,6 @@ class NodeExecutor:
                 target_node.set_parameter_value(target_param_name, param_value)
             target_node.parameter_output_values[target_param_name] = param_value
 
-            # For multi-node packages, also set the value on the proxy node's corresponding output parameter
-            if isinstance(node, NodeGroupProxyNode):
-                sanitized_node_name = target_node_name.replace(" ", "_")
-                proxy_param_name = f"{sanitized_node_name}__{target_param_name}"
-                proxy_param = node.get_parameter_by_name(proxy_param_name)
-                if proxy_param is not None:
-                    if target_param.type != ParameterTypeBuiltin.CONTROL_TYPE:
-                        node.set_parameter_value(proxy_param_name, param_value)
-                    node.parameter_output_values[proxy_param_name] = param_value
-
             logger.debug(
                 "Set parameter '%s' on node '%s' to value: %s",
                 target_param_name,
@@ -526,117 +564,3 @@ class NodeExecutor:
         except ValueError:
             storage_backend = StorageBackend.LOCAL
         return storage_backend
-
-    def _toggle_directional_control_connections(
-        self,
-        proxy_node: BaseNode,
-        node_group: NodeGroup,
-        connections: Connections,
-        *,
-        restore_to_original: bool,
-        is_incoming: bool,
-    ) -> None:
-        """Toggle control connections between proxy and original nodes for a specific direction.
-
-        When a NodeGroupProxyNode is created, control connections from/to the original nodes are
-        redirected to/from the proxy node. Before packaging the flow for execution, we need to
-        temporarily restore these connections back to the original nodes so the packaged flow
-        has the correct control flow structure. After packaging, we toggle them back to the proxy.
-
-        Args:
-            proxy_node: The proxy node containing the node group
-            node_group: The node group data containing original nodes and connection mappings
-            connections: The connections manager that tracks all connections via indexes
-            restore_to_original: If True, restore connections to original nodes (for packaging);
-                               if False, remap connections to proxy (after packaging)
-            is_incoming: If True, handle incoming connections (target_node/target_parameter);
-                        if False, handle outgoing connections (source_node/source_parameter)
-        """
-        # Select the appropriate connection list, mapping, and index based on direction
-        if is_incoming:
-            # Incoming: connections pointing TO nodes in this group
-            connection_list = node_group.external_incoming_connections
-            original_nodes_map = node_group.original_incoming_targets
-            index = connections.incoming_index
-        else:
-            # Outgoing: connections originating FROM nodes in this group
-            connection_list = node_group.external_outgoing_connections
-            original_nodes_map = node_group.original_outgoing_sources
-            index = connections.outgoing_index
-
-        for conn in connection_list:
-            # Get the parameter based on connection direction (target for incoming, source for outgoing)
-            parameter = conn.target_parameter if is_incoming else conn.source_parameter
-
-            # Only toggle control flow connections, skip data connections
-            if parameter.type != ParameterTypeBuiltin.CONTROL_TYPE:
-                continue
-
-            conn_id = id(conn)
-            original_node = original_nodes_map.get(conn_id)
-
-            # Validate we have the original node mapping
-            # Incoming connections must have originals (error if missing)
-            # Outgoing connections may not have originals in some cases (skip if missing)
-            if original_node is None:
-                if is_incoming:
-                    msg = f"No original target found for connection {conn_id} in node group '{node_group.group_id}'"
-                    raise RuntimeError(msg)
-                continue
-
-            # Build the proxy parameter name: {sanitized_node_name}__{parameter_name}
-            # Example: "My Node" with param "enter" -> "My_Node__enter"
-            sanitized_node_name = original_node.name.replace(" ", "_")
-            proxy_param_name = f"{sanitized_node_name}__{parameter.name}"
-
-            # Determine the direction of the toggle
-            if restore_to_original:
-                # Restore: proxy -> original (for packaging)
-                # Before: External -> Proxy -> (internal nodes)
-                # After:  External -> Original node in group
-                from_node = proxy_node
-                from_param = proxy_param_name
-                to_node = original_node
-                to_param = parameter.name
-            else:
-                # Remap: original -> proxy (after packaging)
-                # Before: External -> Original node in group
-                # After:  External -> Proxy -> (internal nodes)
-                from_node = original_node
-                from_param = parameter.name
-                to_node = proxy_node
-                to_param = proxy_param_name
-
-            # Step 1: Remove connection reference from the old node's index
-            if from_node.name in index and from_param in index[from_node.name]:
-                index[from_node.name][from_param].remove(conn_id)
-
-            # Step 2: Update the connection object to point to the new node
-            if is_incoming:
-                conn.target_node = to_node
-            else:
-                conn.source_node = to_node
-
-            # Step 3: Add connection reference to the new node's index
-            index.setdefault(to_node.name, {}).setdefault(to_param, []).append(conn_id)
-
-    def _toggle_control_connections(self, proxy_node: BaseNode, *, restore_to_original: bool) -> None:
-        """Toggle control connections between proxy node and original nodes.
-
-        Args:
-            proxy_node: The proxy node containing the node group
-            restore_to_original: If True, restore connections from proxy to original nodes.
-                               If False, remap connections from original nodes back to proxy.
-        """
-        if not isinstance(proxy_node, NodeGroupProxyNode):
-            return
-        node_group = proxy_node.node_group_data
-        connections = GriptapeNodes.FlowManager().get_connections()
-
-        # Toggle both incoming and outgoing connections
-        self._toggle_directional_control_connections(
-            proxy_node, node_group, connections, restore_to_original=restore_to_original, is_incoming=True
-        )
-        self._toggle_directional_control_connections(
-            proxy_node, node_group, connections, restore_to_original=restore_to_original, is_incoming=False
-        )

{griptape_nodes-0.63.9 → griptape_nodes-0.64.0}/src/griptape_nodes/exe_types/connections.py

@@ -33,7 +33,7 @@ class Connections:
         source_parameter: Parameter,
         target_node: BaseNode,
         target_parameter: Parameter,
-    ) -> bool:
+    ) -> Connection:
         if ParameterMode.OUTPUT not in source_parameter.get_mode():
             errormsg = f"Output Connection not allowed on Parameter '{source_parameter.name}'."
             raise ValueError(errormsg)
@@ -57,7 +57,7 @@ class Connections:
             self.incoming_index.setdefault(target_node.name, {}).setdefault(target_parameter.name, []).append(
                 connection_id
             )
-            return True
+            return connection
         msg = "Connection not allowed because of multiple connections on the same parameter input or control output parameter"
         raise ValueError(msg)
 
@@ -183,6 +183,29 @@ class Connections:
             return connection.source_node, connection.source_parameter
         return None
 
+    def remove_connection_by_object(self, conn: Connection) -> bool:
+        """Remove a connection from the manager by Connection object.
+
+        Args:
+            conn: The Connection object to remove
+
+        Returns:
+            True if connection was removed, False if not found
+        """
+        conn_id = id(conn)
+
+        if conn_id not in self.connections:
+            return False
+
+        self._remove_connection(
+            conn_id,
+            conn.source_node.name,
+            conn.source_parameter.name,
+            conn.target_node.name,
+            conn.target_parameter.name,
+        )
+        return True
+
     def remove_connection(
         self, source_node: str, source_parameter: str, target_node: str, target_parameter: str
     ) -> bool:
@@ -228,6 +251,32 @@ class Connections:
         # delete from the connections dictionary
         del self.connections[connection_id]
 
+    def get_connections_between_nodes(self, node_names: set[str]) -> list[Connection]:
+        """Get all connections where both source and target are in the provided set.
+
+        Args:
+            node_names: Set of node names to check for internal connections
+
+        Returns:
+            List of connections that have both endpoints in the node_names set
+        """
+        internal_connections = []
+
+        for node_name in node_names:
+            if node_name not in self.outgoing_index:
+                continue
+
+            for connection_ids in self.outgoing_index[node_name].values():
+                for conn_id in connection_ids:
+                    if conn_id not in self.connections:
+                        continue
+                    conn = self.connections[conn_id]
+
+                    if conn.target_node.name in node_names:
+                        internal_connections.append(conn)
+
+        return internal_connections
+
     # Used to check data connections for all future nodes to be BAD!
     def unresolve_future_nodes(self, node: BaseNode) -> None:
         # Recursive loop

{griptape_nodes-0.63.9 → griptape_nodes-0.64.0}/src/griptape_nodes/exe_types/flow.py

@@ -7,7 +7,7 @@ if TYPE_CHECKING:
     from queue import Queue
 
     from griptape_nodes.exe_types.core_types import Parameter
-    from griptape_nodes.exe_types.node_types import BaseNode
+    from griptape_nodes.exe_types.node_types import BaseNode, Connection
 
 
 logger = logging.getLogger("griptape_nodes")
@@ -43,7 +43,7 @@ class ControlFlow:
         source_parameter: Parameter,
         target_node: BaseNode,
         target_parameter: Parameter,
-    ) -> bool:
+    ) -> Connection | None:
         if source_node.name in self.nodes and target_node.name in self.nodes:
             from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
@@ -52,7 +52,7 @@ class ControlFlow:
                 .get_connections()
                 .add_connection(source_node, source_parameter, target_node, target_parameter)
             )
-        return False
+        return None
 
     def remove_connection(
         self, source_node: BaseNode, source_parameter: Parameter, target_node: BaseNode, target_parameter: Parameter