griptape-nodes 0.64.11__py3-none-any.whl → 0.65.0__py3-none-any.whl

griptape_nodes/machines/parallel_resolution.py

@@ -5,11 +5,10 @@ import logging
 from enum import StrEnum
 from typing import TYPE_CHECKING
 
+from griptape_nodes.exe_types.base_iterative_nodes import BaseIterativeEndNode, BaseIterativeStartNode
 from griptape_nodes.exe_types.connections import Direction
 from griptape_nodes.exe_types.core_types import Parameter, ParameterTypeBuiltin
 from griptape_nodes.exe_types.node_types import (
-    CONTROL_INPUT_PARAMETER,
-    LOCAL_EXECUTION,
     BaseNode,
     NodeResolutionState,
 )
@@ -117,7 +116,7 @@ class ParallelResolutionContext:
 
 class ExecuteDagState(State):
     @staticmethod
-    async def handle_done_nodes(context: ParallelResolutionContext, done_node: DagNode, network_name: str) -> None:
+    async def handle_done_nodes(context: ParallelResolutionContext, done_node: DagNode, network_name: str) -> None:  # noqa: C901
         current_node = done_node.node_reference
 
         # Check if node was already resolved (shouldn't happen)
@@ -128,12 +127,23 @@ class ExecuteDagState(State):
                 network_name,
             )
             return
+
+        # Special handling for BaseIterativeStartNode
+        # Remove it from the network so the end node can process control flow
+        if isinstance(current_node, BaseIterativeStartNode):
+            current_node.state = NodeResolutionState.RESOLVED
+
+            # Remove start node from ALL networks where it appears
+            for network in list(context.networks.values()):
+                if current_node.name in network.nodes():
+                    network.remove_node(current_node.name)
+
+            return
+
         # Publish all parameter updates.
         current_node.state = NodeResolutionState.RESOLVED
         # Track this as the last resolved node
         context.last_resolved_node = current_node
-        # Track this as the last resolved node
-        context.last_resolved_node = current_node
         # Serialization can be slow so only do it if the user wants debug details.
         if logger.level <= logging.DEBUG:
             logger.debug(
@@ -184,22 +194,13 @@ class ExecuteDagState(State):
         )
         # Now the final thing to do, is to take their directed graph and update it.
         ExecuteDagState.get_next_control_graph(context, current_node, network_name)
-
-    @staticmethod
-    def get_next_control_output_for_non_local_execution(node: BaseNode) -> Parameter | None:
-        for param_name, value in node.parameter_output_values.items():
-            parameter = node.get_parameter_by_name(param_name)
-            if (
-                parameter is not None
-                and parameter.type == ParameterTypeBuiltin.CONTROL_TYPE.value
-                and value == CONTROL_INPUT_PARAMETER
-            ):
-                # This is the parameter
-                logger.debug(
-                    "Parallel Resolution: Found control output parameter '%s' for non-local execution", param_name
-                )
-                return parameter
-        return None
+        graph = context.networks[network_name]
+        if len(graph.nodes()) == 0 and context.dag_builder is not None:
+            # remove from dependencies. This is so we can potentially queue the data node.
+            data_start_nodes = context.dag_builder.remove_graph_from_dependencies()
+            for data_start_node_name in data_start_nodes:
+                data_start_node = GriptapeNodes.NodeManager().get_node_by_name(data_start_node_name)
+                context.dag_builder.add_node_with_dependencies(data_start_node, network_name)
 
     @staticmethod
     def get_next_control_graph(context: ParallelResolutionContext, node: BaseNode, network_name: str) -> None:
@@ -209,15 +210,7 @@ class ExecuteDagState(State):
         # Early returns for various conditions
         if ExecuteDagState._should_skip_control_flow(context, node, network_name, flow_manager):
             return
-        from griptape_nodes.exe_types.node_types import NodeGroupNode
-
-        if (
-            isinstance(node, NodeGroupNode)
-            and node.get_parameter_value(node.execution_environment.name) != LOCAL_EXECUTION
-        ):
-            next_output = ExecuteDagState.get_next_control_output_for_non_local_execution(node)
-        else:
-            next_output = node.get_next_control_output()
+        next_output = node.get_next_control_output()
         if next_output is not None:
             ExecuteDagState._process_next_control_node(context, node, next_output, network_name, flow_manager)
 
@@ -252,7 +245,7 @@ class ExecuteDagState(State):
         flow_manager: FlowManager,
     ) -> None:
         """Process the next control node in the flow."""
-        node_connection = flow_manager.get_connections().get_connected_node(node, next_output)
+        node_connection = flow_manager.get_connections().get_connected_node(node, next_output, include_internal=False)
         if node_connection is not None:
             next_node, next_parameter = node_connection
             # Set entry control parameter
@@ -374,7 +367,8 @@ class ExecuteDagState(State):
             # Reinitialize leaf nodes since maybe we changed things up.
             # We removed nodes from the network. There may be new leaf nodes.
             # Add all leaf nodes from all networks (using set union to avoid duplicates)
-            leaf_nodes.update([n for n in network.nodes() if network.in_degree(n) == 0])
+            network_leaf_nodes = [n for n in network.nodes() if network.in_degree(n) == 0]
+            leaf_nodes.update(network_leaf_nodes)
         canceled_nodes = set()
         queued_nodes = set()
         for node in leaf_nodes:
@@ -434,7 +428,9 @@ class ExecuteDagState(State):
         for node in context.node_to_reference.values():
             # Only queue nodes that are waiting - preserve state of already processed nodes.
             if node.node_state == NodeState.WAITING:
-                node.node_state = NodeState.QUEUED
+                # Use proper queueing method that checks can_queue_control_node()
+                # This prevents premature queueing of nodes with multiple control connections
+                ExecuteDagState._try_queue_waiting_node(context, node.node_reference.name)
 
         context.workflow_state = WorkflowState.NO_ERROR
 
@@ -443,7 +439,7 @@ class ExecuteDagState(State):
         return None
 
     @staticmethod
-    async def on_update(context: ParallelResolutionContext) -> type[State] | None:  # noqa: C901, PLR0911
+    async def on_update(context: ParallelResolutionContext) -> type[State] | None:  # noqa: C901, PLR0911, PLR0912, PLR0915
         # Check if execution is paused
         if context.paused:
             return None
@@ -466,7 +462,9 @@ class ExecuteDagState(State):
         for node in queued_nodes:
             # Process all queued nodes - the async semaphore will handle concurrency limits
             node_reference = context.node_to_reference[node]
-
+            # Skip BaseIterativeEndNode as it's handled by loop execution flow
+            if isinstance(node_reference.node_reference, BaseIterativeEndNode):
+                continue
             # Collect parameter values from upstream nodes before executing
             try:
                 await ExecuteDagState.collect_values_from_upstream_nodes(node_reference)
@@ -487,6 +485,34 @@ class ExecuteDagState(State):
                 logger.error(msg)
                 return ErrorState
 
+            # We've set up the node for success completely. Now we check and handle accordingly if it's a for-each-start node
+            # if False:
+            if isinstance(node_reference.node_reference, BaseIterativeStartNode):
+                # Call handle_done_state to clear it from everything
+                end_loop_node = node_reference.node_reference.end_node
+                # Set start node to DONE! even if it isn't truly done lolllll.
+                node_reference.node_state = NodeState.DONE
+                if end_loop_node is None:
+                    msg = (
+                        f"Cannot have a Start Loop Node without an End Loop Node: {node_reference.node_reference.name}"
+                    )
+                    logger.error(msg)
+                    return ErrorState
+                # We're going to skip straight to the end node here instead.
+                # Set end node to node reference
+                if context.dag_builder is not None:
+                    # Check if BaseIterativeEndNode is already in DAG (from pre-building phase)
+                    if end_loop_node.name in context.dag_builder.node_to_reference:
+                        # BaseIterativeEndNode already exists in DAG, just get reference and queue it
+                        end_node_reference = context.dag_builder.node_to_reference[end_loop_node.name]
+                        end_node_reference.node_state = NodeState.QUEUED
+                        node_reference = end_node_reference
+                    else:
+                        # BaseIterativeEndNode not in DAG yet (backwards compatibility), add it
+                        end_node_reference = context.dag_builder.add_node(end_loop_node)
+                        end_node_reference.node_state = NodeState.QUEUED
+                        node_reference = end_node_reference
+
             def on_task_done(task: asyncio.Task) -> None:
                 if task in context.task_to_node:
                     node = context.task_to_node[task]

griptape_nodes/machines/sequential_resolution.py

@@ -7,7 +7,7 @@ from typing import Any
 
 from griptape_nodes.exe_types.connections import Direction
 from griptape_nodes.exe_types.core_types import ParameterTypeBuiltin
-from griptape_nodes.exe_types.node_types import LOCAL_EXECUTION, BaseNode, NodeGroupNode, NodeResolutionState
+from griptape_nodes.exe_types.node_types import BaseNode, NodeResolutionState
 from griptape_nodes.exe_types.type_validator import TypeValidator
 from griptape_nodes.machines.fsm import FSM, State
 from griptape_nodes.node_library.library_registry import LibraryRegistry
@@ -79,42 +79,6 @@ class InitializeSpotlightState(State):
             return CompleteState
         current_node = context.current_node
 
-        # If this node has a non-LOCAL parent group, redirect to parent instead
-        # Handle nested groups recursively - keep redirecting until we find the top-level parent
-        from griptape_nodes.exe_types.node_types import LOCAL_EXECUTION, NodeGroupNode
-
-        while current_node.parent_group is not None and isinstance(current_node.parent_group, NodeGroupNode):
-            execution_env = current_node.parent_group.get_parameter_value(
-                current_node.parent_group.execution_environment.name
-            )
-            if execution_env != LOCAL_EXECUTION:
-                # Replace current node with parent group
-                parent_group = current_node.parent_group
-                logger.info(
-                    "Sequential Resolution: Redirecting from child node '%s' to parent node group '%s' at InitializeSpotlight",
-                    current_node.name,
-                    parent_group.name,
-                )
-                # Update the focus stack to use parent instead
-                context.focus_stack[-1] = Focus(node=parent_group)
-                current_node = parent_group
-                # Continue loop to check if this parent also has a parent
-            else:
-                # Parent is LOCAL_EXECUTION, stop redirecting
-                break
-
-        # For NodeGroups, check external connections for unresolved dependencies
-        if isinstance(current_node, NodeGroupNode):
-            unresolved_dependency = EvaluateParameterState._check_node_group_external_dependencies(current_node)
-            if unresolved_dependency:
-                logger.info(
-                    "Sequential Resolution: NodeGroup '%s' has unresolved external dependency on '%s', queuing dependency first",
-                    current_node.name,
-                    unresolved_dependency.name,
-                )
-                context.focus_stack.append(Focus(node=unresolved_dependency))
-                return InitializeSpotlightState
-
         if current_node.state == NodeResolutionState.UNRESOLVED:
             # Mark all future nodes unresolved.
             # TODO: https://github.com/griptape-ai/griptape-nodes/issues/862
@@ -161,7 +125,7 @@ class EvaluateParameterState(State):
     @staticmethod
     def _get_next_node(current_node: BaseNode, current_parameter: Any, connections: Any) -> BaseNode | None:
         """Get the next node connected to the current parameter."""
-        next_node = connections.get_connected_node(current_node, current_parameter)
+        next_node = connections.get_connected_node(current_node, current_parameter, include_internal=False)
         if next_node:
             next_node, _ = next_node
         return next_node
@@ -173,73 +137,6 @@ class EvaluateParameterState(State):
             msg = f"Cycle detected between node '{current_node.name}' and '{next_node.name}'."
             raise RuntimeError(msg)
 
-    @staticmethod
-    def _handle_parent_already_resolved(current_node: BaseNode) -> type[State]:
-        """Handle case where parent node group is already resolved."""
-        if current_node.advance_parameter():
-            return InitializeSpotlightState
-        return ExecuteNodeState
-
-    @staticmethod
-    def _check_node_group_external_dependencies(node_group: BaseNode) -> BaseNode | None:
-        """Check if NodeGroup has unresolved external incoming connections.
-
-        Returns the first unresolved source node (or its parent if applicable) if found, None otherwise.
-        """
-        if not isinstance(node_group, NodeGroupNode):
-            return None
-
-        for conn in node_group.stored_connections.external_connections.incoming_connections:
-            source_node = conn.source_node
-            if source_node.state == NodeResolutionState.UNRESOLVED:
-                # Check if source has a parent group to use instead
-                if source_node.parent_group is not None and isinstance(source_node.parent_group, NodeGroupNode):
-                    execution_env = source_node.parent_group.get_parameter_value(
-                        source_node.parent_group.execution_environment.name
-                    )
-                    if execution_env != LOCAL_EXECUTION:
-                        return source_node.parent_group
-                return source_node
-        return None
-
-    @staticmethod
-    def _determine_node_to_queue(
-        next_node: BaseNode, current_node: BaseNode, focus_stack_names: set[str]
-    ) -> BaseNode | None:
-        """Determine which node to queue - the next node or its parent group.
-
-        Returns None if the parent node group is already resolved.
-        """
-        if next_node.parent_group is None or not isinstance(next_node.parent_group, NodeGroupNode):
-            return next_node
-
-        parent_group = next_node.parent_group
-        execution_env = parent_group.get_parameter_value(parent_group.execution_environment.name)
-        if execution_env == LOCAL_EXECUTION:
-            return next_node
-
-        if parent_group.state == NodeResolutionState.RESOLVED:
-            logger.info(
-                "Sequential Resolution: Parent node group '%s' is already resolved, skipping child node '%s' (execution environment: %s)",
-                parent_group.name,
-                next_node.name,
-                execution_env,
-            )
-            return None
-
-        if parent_group.name in focus_stack_names:
-            msg = f"Cycle detected: parent node group '{parent_group.name}' is already in focus stack while processing dependency for '{current_node.name}'."
-            raise RuntimeError(msg)
-
-        logger.info(
-            "Sequential Resolution: Queuing parent node group '%s' instead of child node '%s' (execution environment: %s) - child is a dependency of '%s'",
-            parent_group.name,
-            next_node.name,
-            execution_env,
-            current_node.name,
-        )
-        return parent_group
-
     @staticmethod
     async def on_update(context: ResolutionContext) -> type[State] | None:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
@@ -258,11 +155,7 @@ class EvaluateParameterState(State):
             focus_stack_names = {focus.node.name for focus in context.focus_stack}
             EvaluateParameterState._check_for_cycle(next_node, current_node, focus_stack_names)
 
-            node_to_queue = EvaluateParameterState._determine_node_to_queue(next_node, current_node, focus_stack_names)
-            if node_to_queue is None:
-                return EvaluateParameterState._handle_parent_already_resolved(current_node)
-
-            context.focus_stack.append(Focus(node=node_to_queue))
+            context.focus_stack.append(Focus(node=next_node))
             return InitializeSpotlightState
 
         if current_node.advance_parameter():
@@ -290,7 +183,9 @@ class ExecuteNodeState(State):
 
         for parameter in current_node.parameters:
             # Get the connected upstream node for this parameter
-            upstream_connection = connections.get_connected_node(current_node, parameter, direction=Direction.UPSTREAM)
+            upstream_connection = connections.get_connected_node(
+                current_node, parameter, direction=Direction.UPSTREAM, include_internal=False
+            )
             if upstream_connection:
                 upstream_node, upstream_parameter = upstream_connection
 
@@ -413,7 +308,7 @@ class ExecuteNodeState(State):
                 return CompleteState
             except Exception as e:
                 logger.exception("Error processing node '%s", current_node.name)
-                msg = f"Canceling flow run. Node '{current_node.name}' encountered a problem: {e}"
+                msg = f"Node '{current_node.name}' encountered a problem: {e}"
                 # Mark the node as unresolved, broadcasting to everyone.
                 current_node.make_node_unresolved(
                     current_states_to_trigger_change_event=set(
@@ -423,7 +318,10 @@ class ExecuteNodeState(State):
 
                 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
-                await GriptapeNodes.FlowManager().cancel_flow_run()
+                # Do NOT call cancel_flow_run() here - that cancels the global main flow!
+                # When executing in a subflow (e.g., for-each loop iteration), we want to
+                # terminate only the current subflow, not the entire main workflow.
+                # The exception will propagate up to the caller, which will handle it appropriately.
 
                 GriptapeNodes.EventManager().put_event(
                     ExecutionGriptapeNodeEvent(

griptape_nodes/retained_mode/events/app_events.py

@@ -109,6 +109,7 @@ class AppGetSessionResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
 class AppInitializationComplete(AppPayload):
     """Application initialization completed successfully. All subsystems ready."""
 
+    libraries_to_download: list[str] = field(default_factory=list)
     libraries_to_register: list[str] = field(default_factory=list)
     workflows_to_register: list[str] = field(default_factory=list)
     models_to_download: list[str] = field(default_factory=list)

griptape_nodes/retained_mode/events/base_events.py

@@ -35,7 +35,6 @@ class ResultDetails:
         *result_details: ResultDetail,
         message: str | None = None,
         level: int | None = None,
-        logger: logging.Logger | str | None = "griptape_nodes",
     ):
         """Initialize with ResultDetail objects or create a single one from message/level.
 
@@ -43,7 +42,6 @@ class ResultDetails:
             *result_details: Variable number of ResultDetail objects
             message: If provided, creates a single ResultDetail with this message
             level: Logging level for the single ResultDetail (required if message is provided)
-            logger: Logger to use for auto-logging. String for logger name, Logger object, or None to skip
         """
         # Handle single message/level convenience
         if message is not None:
@@ -60,18 +58,13 @@ class ResultDetails:
                 raise ValueError(err_msg)
             self.result_details = list(result_details)
 
-        # Auto-log if logger is provided
-        if logger is not None:
-            try:
-                if isinstance(logger, str):
-                    logger = logging.getLogger(logger)
+    def __str__(self) -> str:
+        """String representation of ResultDetails.
 
-                for detail in self.result_details:
-                    # Handle both string and int levels
-                    logger.log(detail.level, detail.message)
-            except Exception:  # noqa: S110
-                # If logging fails for any reason, don't let it break the ResultDetails creation
-                pass
+        Returns:
+            str: Concatenated messages of all ResultDetail objects
+        """
+        return "\n".join(detail.message for detail in self.result_details)
 
 
 # The Payload class is a marker interface
@@ -82,7 +75,17 @@ class Payload(ABC):  # noqa: B024
 # Request payload base class with optional request ID
 @dataclass(kw_only=True)
 class RequestPayload(Payload, ABC):
+    """Base class for all request payloads.
+
+    Args:
+        request_id: Optional request ID for tracking.
+        failure_log_level: If set, override the log level for failure results.
+                          Use logging.DEBUG (10) or logging.INFO (20) to suppress error toasts.
+                          Default: None (use handler's default, typically ERROR).
+    """
+
     request_id: int | None = None
+    failure_log_level: int | None = None
 
 
 # Result payload base class with abstract succeeded/failed methods, and indicator whether the current workflow was altered.

griptape_nodes/retained_mode/events/connection_events.py

@@ -24,6 +24,7 @@ class CreateConnectionRequest(RequestPayload):
         source_node_name: Name of the source node (None for current context)
         target_node_name: Name of the target node (None for current context)
         initial_setup: Skip setup work when loading from file
+        is_node_group_internal: Mark this connection as internal to a node group (for DAG building)
 
     Results: CreateConnectionResultSuccess | CreateConnectionResultFailure (incompatible types, invalid nodes/parameters)
     """
@@ -35,6 +36,8 @@ class CreateConnectionRequest(RequestPayload):
     target_node_name: str | None = None
     # initial_setup prevents unnecessary work when we are loading a workflow from a file.
     initial_setup: bool = False
+    # Mark this connection as internal to a node group proxy parameter
+    is_node_group_internal: bool = False
 
 
 @dataclass

griptape_nodes/retained_mode/events/execution_events.py

@@ -95,6 +95,41 @@ class StartFlowResultFailure(ResultPayloadFailure):
     validation_exceptions: list[Exception]
 
 
+@dataclass
+@PayloadRegistry.register
+class StartLocalSubflowRequest(RequestPayload):
+    """Start an independent local subflow that runs concurrently with the main flow.
+
+    Use when: Running loop iterations or other independent subflows that need their own
+    execution context and should not interfere with the main flow's state.
+
+    This creates a separate ControlFlowMachine with its own DagBuilder to ensure full isolation.
+
+    Args:
+        flow_name: Name of the flow to start as a subflow
+        start_node: The node to start execution from (None to auto-detect start node)
+        pickle_control_flow_result: Whether to pickle the result for subprocess retrieval
+
+    Results: StartLocalSubflowResultSuccess | StartLocalSubflowResultFailure
+    """
+
+    flow_name: str
+    start_node: str | None = None
+    pickle_control_flow_result: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class StartLocalSubflowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Local subflow started successfully and is running independently."""
+
+
+@dataclass
+@PayloadRegistry.register
+class StartLocalSubflowResultFailure(ResultPayloadFailure):
+    """Local subflow failed to start. Check result_details for error information."""
+
+
 @dataclass
 @PayloadRegistry.register
 class StartFlowFromNodeRequest(RequestPayload):

griptape_nodes/retained_mode/events/flow_events.py

@@ -238,6 +238,7 @@ class SerializedFlowCommands:
     sub_flows_commands: list[SerializedFlowCommands]
     node_dependencies: NodeDependencies
     node_types_used: set[LibraryNameAndNodeType]
+    flow_name: str | None = None
 
 
 @dataclass
@@ -278,6 +279,7 @@ class DeserializeFlowFromCommandsRequest(RequestPayload):
 @PayloadRegistry.register
 class DeserializeFlowFromCommandsResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
     flow_name: str
+    node_name_mappings: dict[str, str] = field(default_factory=dict)  # original_name -> deserialized_name
 
 
 @dataclass
@@ -394,6 +396,7 @@ class SetFlowMetadataResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure
 SanitizedParameterName = str  # What appears in the serialized flow
 OriginalNodeName = str  # Original node name (can have spaces, dots, etc.)
 OriginalParameterName = str  # Original parameter name
+PackagedNodeName = str  # Name of Start/End node in packaged flow
 
 
 class OriginalNodeParameter(NamedTuple):
@@ -403,6 +406,13 @@ class OriginalNodeParameter(NamedTuple):
     parameter_name: OriginalParameterName
 
 
+class PackagedNodeParameterMapping(NamedTuple):
+    """Parameter mappings for a packaged node (Start or End)."""
+
+    node_name: PackagedNodeName  # Name of the packaged node (e.g., "Start_Package_MultiNode")
+    parameter_mappings: dict[SanitizedParameterName, OriginalNodeParameter]  # Parameter name -> original node/param
+
+
 class ParameterNameMapping(NamedTuple):
     """Maps a sanitized parameter name back to its original node and parameter."""
 
@@ -446,6 +456,7 @@ class PackageNodesAsSerializedFlowRequest(RequestPayload):
     entry_control_node_name: str | None = None
     entry_control_parameter_name: str | None = None
     output_parameter_prefix: str = "packaged_node_"
+    node_group_name: str | None = None  # Name of the NodeGroupNode if packaging a group
 
 
 @dataclass
@@ -457,13 +468,15 @@ class PackageNodesAsSerializedFlowResultSuccess(WorkflowNotAlteredMixin, ResultP
         serialized_flow_commands: The complete serialized flow with StartFlow, selected nodes with preserved connections, and EndFlow
         workflow_shape: The workflow shape defining inputs and outputs for external callers
         packaged_node_names: List of node names that were included in the package
-        parameter_name_mappings: Dict mapping sanitized parameter names to original node and parameter names for O(1) lookup
+        parameter_name_mappings: List of parameter mappings for packaged nodes.
+            Index 0 = Start node mappings, Index 1 = End node mappings.
+            Each entry contains the node name and its parameter mappings.
     """
 
     serialized_flow_commands: SerializedFlowCommands
     workflow_shape: WorkflowShape
     packaged_node_names: list[str]
-    parameter_name_mappings: dict[SanitizedParameterName, OriginalNodeParameter]
+    parameter_name_mappings: list[PackagedNodeParameterMapping]
 
 
 @dataclass