griptape-nodes 0.57.1__py3-none-any.whl → 0.58.0__py3-none-any.whl

griptape_nodes/drivers/storage/local_storage_driver.py

@@ -58,7 +58,7 @@ class LocalStorageDriver(BaseStorageDriver):
 
     def create_signed_download_url(self, path: Path) -> str:
         # The base_url already includes the /static path, so just append the path
-        url = f"{self.base_url}/{path}"
+        url = f"{self.base_url}/{path.as_posix()}"
         # Add a cache-busting query parameter to the URL so that the browser always reloads the file
         cache_busted_url = f"{url}?t={int(time.time())}"
         return cache_busted_url
@@ -70,7 +70,7 @@ class LocalStorageDriver(BaseStorageDriver):
             path: The path of the file to delete.
         """
         # Use the static server's delete endpoint
-        delete_url = urljoin(self.base_url, f"/static-files/{path}")
+        delete_url = urljoin(self.base_url, f"/static-files/{path.as_posix()}")
 
         try:
             response = httpx.delete(delete_url)

griptape_nodes/exe_types/connections.py

@@ -1,5 +1,6 @@
 import logging
 from dataclasses import dataclass
+from enum import StrEnum
 
 from griptape_nodes.exe_types.core_types import Parameter, ParameterMode, ParameterTypeBuiltin
 from griptape_nodes.exe_types.node_types import BaseNode, Connection, EndLoopNode, NodeResolutionState, StartLoopNode
@@ -7,6 +8,11 @@ from griptape_nodes.exe_types.node_types import BaseNode, Connection, EndLoopNod
 logger = logging.getLogger("griptape_nodes")
 
 
+class Direction(StrEnum):
+    UPSTREAM = "upstream"
+    DOWNSTREAM = "downstream"
+
+
 @dataclass
 class Connections:
     # store connections as IDs
@@ -127,28 +133,50 @@ class Connections:
                         return connection.source_node, connection.source_parameter
         return None  # No connection found for this control parameter
 
-    def get_connected_node(self, node: BaseNode, parameter: Parameter) -> tuple[BaseNode, Parameter] | None:
+    def get_connected_node(
+        self, node: BaseNode, parameter: Parameter, direction: Direction | None = None
+    ) -> tuple[BaseNode, Parameter] | None:
         # Check to see if we should be getting the next connection or the previous connection based on the parameter.
         # Override this method for EndLoopNodes - these might have to go backwards or forwards.
-        if isinstance(node, EndLoopNode) and ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
-            return self._get_connected_node_for_end_loop_control(node, parameter)
-        if ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
-            connections = self.outgoing_index
+        if direction is not None:
+            # We've added direction as an override, since we sometimes need to get connections in a certain direction regardless of parameter types.
+            if direction == Direction.UPSTREAM:
+                connections = self.incoming_index
+            elif direction == Direction.DOWNSTREAM:
+                connections = self.outgoing_index
         else:
-            connections = self.incoming_index
+            if isinstance(node, EndLoopNode) and ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
+                return self._get_connected_node_for_end_loop_control(node, parameter)
+            if ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
+                connections = self.outgoing_index
+                # We still default to downstream (forwards) connections for control parameters
+                direction = Direction.DOWNSTREAM
+            else:
+                connections = self.incoming_index
+                # And upstream (backwards) connections for data parameters.
+                direction = Direction.UPSTREAM
         connections_from_node = connections.get(node.name, {})
 
         connection_id = connections_from_node.get(parameter.name, [])
         # TODO: https://github.com/griptape-ai/griptape-nodes/issues/859
         if not len(connection_id):
             return None
-        if len(connection_id) > 1:
-            msg = "There should not be more than one connection here."
+        # Right now, our special case is that it is ok to have multiple inputs to a CONTROL_TYPE parameter, so if we're going upstream, it's ok. And it's ok to have multiple downstream outputs from a data type parameter.
+        if (
+            len(connection_id) > 1
+            and not (
+                direction == Direction.UPSTREAM and parameter.output_type == ParameterTypeBuiltin.CONTROL_TYPE.value
+            )
+            and not (
+                direction == Direction.DOWNSTREAM and parameter.output_type != ParameterTypeBuiltin.CONTROL_TYPE.value
+            )
+        ):
+            msg = f"There should not be more than one {direction} connection here to/from {node.name}.{parameter.name}"
             raise ValueError(msg)
         connection_id = connection_id[0]
         if connection_id in self.connections:
             connection = self.connections[connection_id]
-            if ParameterTypeBuiltin.CONTROL_TYPE.value == parameter.output_type:
+            if direction == Direction.DOWNSTREAM:
                 # Return the target (next place to go)
                 return connection.target_node, connection.target_parameter
             # Return the source (next place to chain back to)

griptape_nodes/exe_types/core_types.py

@@ -1313,7 +1313,7 @@ class ControlParameter(Parameter, ABC):
         super().__init__(
             type=ParameterTypeBuiltin.CONTROL_TYPE.value,
             default_value=None,
-            settable=False,
+            settable=True,
             name=name,
             tooltip=tooltip,
             input_types=input_types,

griptape_nodes/exe_types/node_types.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-import asyncio
 import logging
+import threading
+import warnings
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Generator, Iterable
-from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field
 from enum import StrEnum, auto
 from typing import TYPE_CHECKING, Any, NamedTuple, TypeVar
@@ -31,16 +31,13 @@ from griptape_nodes.retained_mode.events.base_events import (
     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,
 )
 from griptape_nodes.traits.options import Options
+from griptape_nodes.utils import async_utils
 
 if TYPE_CHECKING:
     from griptape_nodes.exe_types.core_types import NodeMessagePayload
@@ -53,6 +50,8 @@ T = TypeVar("T")
 AsyncResult = Generator[Callable[[], T], T]
 
 LOCAL_EXECUTION = "Local Execution"
+PRIVATE_EXECUTION = "Private Execution"
+CONTROL_INPUT_PARAMETER = "Control Input Selection"
 
 
 class ImportDependency(NamedTuple):
@@ -116,8 +115,8 @@ def get_library_names_with_publish_handlers() -> list[str]:
     library_manager = GriptapeNodes.LibraryManager()
     event_handlers = library_manager.get_registered_event_handlers(PublishWorkflowRequest)
 
-    # Always include "local" as the first option
-    library_names = [LOCAL_EXECUTION]
+    # Always include "local" and "private" as the first options
+    library_names = [LOCAL_EXECUTION, PRIVATE_EXECUTION]
 
     # Add all registered library names that can handle PublishWorkflowRequest
     library_names.extend(sorted(event_handlers.keys()))
@@ -131,17 +130,18 @@ class BaseNode(ABC):
     metadata: dict[Any, Any]
 
     # Node Context Fields
-    state: NodeResolutionState
     current_spotlight_parameter: Parameter | None = None
     parameter_values: dict[str, Any]
     parameter_output_values: TrackedParameterOutputValues
     stop_flow: bool = False
     root_ui_element: BaseNodeElement
+    _state: NodeResolutionState
     _tracked_parameters: list[BaseNodeElement]
     _entry_control_parameter: Parameter | None = (
         None  # The control input parameter used to enter this node during execution
     )
     lock: bool = False  # When lock is true, the node is locked and can't be modified. When lock is false, the node is unlocked and can be modified.
+    _cancellation_requested: threading.Event  # Event indicating if cancellation has been requested for this node
 
     @property
     def parameters(self) -> list[Parameter]:
@@ -157,7 +157,7 @@ class BaseNode(ABC):
         state: NodeResolutionState = NodeResolutionState.UNRESOLVED,
     ) -> None:
         self.name = name
-        self.state = state
+        self._state = state
         if metadata is None:
             self.metadata = {}
         else:
@@ -169,6 +169,7 @@ class BaseNode(ABC):
         self.root_ui_element._node_context = self
         self.process_generator = None
         self._tracked_parameters = []
+        self._cancellation_requested = threading.Event()
         self.set_entry_control_parameter(None)
         self.execution_environment = Parameter(
             name="execution_environment",
@@ -181,6 +182,18 @@ class BaseNode(ABC):
         )
         self.add_parameter(self.execution_environment)
 
+    @property
+    def state(self) -> NodeResolutionState:
+        """Get the current resolution state of the node.
+
+        Existence as @property facilitates subclasses overriding the getter for dynamic/computed state.
+        """
+        return self._state
+
+    @state.setter
+    def state(self, new_state: NodeResolutionState) -> None:
+        self._state = new_state
+
     # This is gross and we need to have a universal pass on resolution state changes and emission of events. That's what this ticket does!
     # https://github.com/griptape-ai/griptape-nodes/issues/994
     def make_node_unresolved(self, current_states_to_trigger_change_event: set[NodeResolutionState] | None) -> None:
@@ -190,6 +203,7 @@ class BaseNode(ABC):
         if current_states_to_trigger_change_event is not None and self.state in current_states_to_trigger_change_event:
             # Trigger the change event.
             # Send an event to the GUI so it knows this node has changed resolution state.
+            from griptape_nodes.retained_mode.events.execution_events import NodeUnresolvedEvent
 
             GriptapeNodes.EventManager().put_event(
                 ExecutionGriptapeNodeEvent(
@@ -210,6 +224,27 @@ class BaseNode(ABC):
         """
         self._entry_control_parameter = parameter
 
+    @property
+    def is_cancellation_requested(self) -> bool:
+        """Check if cancellation has been requested for this node.
+
+        Returns:
+            True if cancellation has been requested, False otherwise
+        """
+        return self._cancellation_requested.is_set()
+
+    def request_cancellation(self) -> None:
+        """Request cancellation of this node's execution.
+
+        Sets a flag that the node can check during long-running operations
+        to cooperatively cancel execution.
+        """
+        self._cancellation_requested.set()
+
+    def clear_cancellation(self) -> None:
+        """Clear the cancellation request flag."""
+        self._cancellation_requested.clear()
+
     def emit_parameter_changes(self) -> None:
         if self._tracked_parameters:
             for parameter in self._tracked_parameters:
@@ -816,20 +851,14 @@ class BaseNode(ABC):
             return
 
         if isinstance(result, Generator):
-            # Handle generator pattern asynchronously using the same logic as before
-            loop = asyncio.get_running_loop()
-
             try:
                 # Start the generator
                 func = next(result)
 
                 while True:
-                    # Run callable in thread pool (preserving existing behavior)
-                    with ThreadPoolExecutor() as executor:
-                        future_result = await loop.run_in_executor(executor, func)
-
                     # Send result back and get next callable
-                    func = result.send(future_result)
+                    func_result = await async_utils.to_thread(func)
+                    func = result.send(func_result)
 
             except StopIteration:
                 # Generator is done
@@ -871,12 +900,26 @@ class BaseNode(ABC):
     def get_config_value(self, service: str, value: str) -> str:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
+        warnings.warn(
+            "get_config_value() is deprecated. Use GriptapeNodes.SecretsManager().get_secret() for secrets/API keys "
+            "or GriptapeNodes.ConfigManager().get_config_value() for other config values.",
+            UserWarning,
+            stacklevel=2,
+        )
+
         config_value = GriptapeNodes.ConfigManager().get_config_value(f"nodes.{service}.{value}")
         return config_value
 
     def set_config_value(self, service: str, value: str, new_value: str) -> None:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
+        warnings.warn(
+            "set_config_value() is deprecated. Use GriptapeNodes.SecretsManager().set_secret() for secrets/API keys "
+            "or GriptapeNodes.ConfigManager().set_config_value() for other config values.",
+            UserWarning,
+            stacklevel=2,
+        )
+
         GriptapeNodes.ConfigManager().set_config_value(f"nodes.{service}.{value}", new_value)
 
     def clear_node(self) -> None:
@@ -884,6 +927,8 @@ class BaseNode(ABC):
         self.state = NodeResolutionState.UNRESOLVED
         # delete all output values potentially generated
         self.parameter_output_values.clear()
+        # Clear cancellation flag
+        self.clear_cancellation()
         # Clear the spotlight linked list
         # First, clear all next/prev pointers to break the linked list
         current = self.current_spotlight_parameter
@@ -946,6 +991,7 @@ class BaseNode(ABC):
         )
 
     def publish_update_to_parameter(self, parameter_name: str, value: Any) -> None:
+        from griptape_nodes.retained_mode.events.execution_events import ParameterValueUpdateEvent
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
         parameter = self.get_parameter_by_name(parameter_name)
@@ -1008,7 +1054,10 @@ class BaseNode(ABC):
 
         # Verify we have all elements
         if len(ordered_elements) != len(current_elements):
-            msg = "Element order must include all elements exactly once"
+            ordered_names = {e.name for e in ordered_elements}
+            current_names = {e.name for e in current_elements}
+            diff = current_names - ordered_names
+            msg = f"Element order must include all elements exactly once. Missing from new order: {diff}"
             raise ValueError(msg)
 
         # Remove all elements from root_ui_element
@@ -1182,6 +1231,47 @@ class BaseNode(ABC):
         # Use reorder_elements to apply the move
         self.reorder_elements(list(new_order))
 
+    def get_element_index(self, element: str | BaseNodeElement, root: BaseNodeElement | None = None) -> int:
+        """Get the current index of an element in the element list.
+
+        Args:
+            element: The element to get the index for, specified by name or element object
+            root: The root element to search within. If None, uses root_ui_element
+
+        Returns:
+            The current index of the element (0-based)
+
+        Raises:
+            ValueError: If element is not found
+
+        Example:
+            # Get index by name in root container
+            index = node.get_element_index("element1")
+
+            # Get index within a specific parameter group
+            group = node.get_element_by_name_and_type("my_group", ParameterGroup)
+            index = node.get_element_index("parameter1", root=group)
+
+            # Get index of a parameter to position another element relative to it
+            reference_index = node.get_element_index("some_parameter")
+            node.move_element_to_position("new_parameter", reference_index + 1)
+        """
+        # Use root_ui_element if no root specified
+        if root is None:
+            root = self.root_ui_element
+
+        # Get list of all element names in the root
+        element_names = [child.name for child in root._children]
+
+        # Get element name
+        if isinstance(element, str):
+            element_name = element
+        else:
+            element_name = element.name
+
+        # Find the index of the element
+        return element_names.index(element_name)
+
 
 class TrackedParameterOutputValues(dict[str, Any]):
     """A dictionary that tracks modifications and emits AlterElementEvent when parameter output values change."""
@@ -1476,13 +1566,16 @@ class EndNode(BaseNode):
             case self.succeeded_control:
                 was_successful = True
                 status_prefix = "[SUCCEEDED]"
+                logger.debug("End Node '%s': Matched succeeded_control path", self.name)
             case self.failed_control:
                 was_successful = False
                 status_prefix = "[FAILED]"
+                logger.debug("End Node '%s': Matched failed_control path", self.name)
             case _:
                 # No specific success/failure connection provided, assume success
                 was_successful = True
                 status_prefix = "[SUCCEEDED] No connection provided for success or failure, assuming successful"
+                logger.debug("End Node '%s': No specific control connection, assuming success", self.name)
 
         # Get result details and format the final message
         result_details_value = self.get_parameter_value("result_details")
@@ -1500,10 +1593,10 @@ class EndNode(BaseNode):
             if param.type != ParameterTypeBuiltin.CONTROL_TYPE:
                 value = self.get_parameter_value(param.name)
                 self.parameter_output_values[param.name] = value
-        next_control_output = self.get_next_control_output()
+        entry_parameter = self._entry_control_parameter
         # Update which control parameter to flag as the output value.
-        if next_control_output is not None:
-            self.parameter_output_values[next_control_output.name] = 1
+        if entry_parameter is not None:
+            self.parameter_output_values[entry_parameter.name] = CONTROL_INPUT_PARAMETER
 
 
 class StartLoopNode(BaseNode):

griptape_nodes/machines/control_flow.py

@@ -5,9 +5,8 @@ import logging
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from griptape_nodes.exe_types.core_types import Parameter
-from griptape_nodes.exe_types.node_types import BaseNode, NodeResolutionState
-from griptape_nodes.exe_types.type_validator import TypeValidator
+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
 from griptape_nodes.machines.fsm import FSM, State
 from griptape_nodes.machines.parallel_resolution import ParallelResolutionMachine
 from griptape_nodes.machines.sequential_resolution import SequentialResolutionMachine
@@ -45,6 +44,7 @@ class ControlFlowContext:
     selected_output: Parameter | None
     paused: bool = False
     flow_name: str
+    pickle_control_flow_result: bool
 
     def __init__(
         self,
@@ -52,6 +52,7 @@ class ControlFlowContext:
         max_nodes_in_parallel: int,
         *,
         execution_type: WorkflowExecutionMode = WorkflowExecutionMode.SEQUENTIAL,
+        pickle_control_flow_result: bool = False,
     ) -> None:
         self.flow_name = flow_name
         if execution_type == WorkflowExecutionMode.PARALLEL:
@@ -65,6 +66,7 @@ class ControlFlowContext:
         else:
             self.resolution_machine = SequentialResolutionMachine()
         self.current_nodes = []
+        self.pickle_control_flow_result = pickle_control_flow_result
 
     def get_next_nodes(self, output_parameter: Parameter | None = None) -> list[NextNodeInfo]:
         """Get all next nodes from the current nodes.
@@ -84,7 +86,10 @@ class ControlFlowContext:
                     next_nodes.append(NextNodeInfo(node=node, entry_parameter=entry_parameter))
             else:
                 # Get next control output for this node
-                next_output = current_node.get_next_control_output()
+                if current_node.get_parameter_value(current_node.execution_environment.name) != LOCAL_EXECUTION:
+                    next_output = self.get_next_control_output_for_non_local_execution(current_node)
+                else:
+                    next_output = current_node.get_next_control_output()
                 if next_output is not None:
                     node_connection = (
                         GriptapeNodes.FlowManager().get_connections().get_connected_node(current_node, next_output)
@@ -92,6 +97,8 @@ class ControlFlowContext:
                     if node_connection is not None:
                         node, entry_parameter = node_connection
                         next_nodes.append(NextNodeInfo(node=node, entry_parameter=entry_parameter))
+                else:
+                    logger.debug("Control Flow: Node '%s' has no control output", current_node.name)
 
         # If no connections found, check execution queue
         if not next_nodes:
@@ -101,6 +108,20 @@ class ControlFlowContext:
 
         return next_nodes
 
+    # Mirrored in @parallel_resolution.py. if you update one, update the other.
+    def get_next_control_output_for_non_local_execution(self, 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
+                and value == CONTROL_INPUT_PARAMETER
+            ):
+                # This is the parameter
+                logger.debug("Control Flow: Found control output parameter '%s' for non-local execution", param_name)
+                return parameter
+        return None
+
     def reset(self, *, cancel: bool = False) -> None:
         if self.current_nodes is not None:
             for node in self.current_nodes:
@@ -152,7 +173,11 @@ class ResolveNodeState(State):
         await context.resolution_machine.resolve_node(current_node)
 
         if context.resolution_machine.is_complete():
+            # Get the last resolved node from the DAG and set it as current
             if isinstance(context.resolution_machine, ParallelResolutionMachine):
+                last_resolved_node = context.resolution_machine.get_last_resolved_node()
+                if last_resolved_node:
+                    context.current_nodes = [last_resolved_node]
                 return CompleteState
             return NextNodeState
         return None
@@ -219,12 +244,19 @@ class CompleteState(State):
     async def on_enter(context: ControlFlowContext) -> type[State] | None:
         # Broadcast completion events for any remaining current nodes
         for current_node in context.current_nodes:
+            # Use pickle-based serialization for complex parameter output values
+            from griptape_nodes.retained_mode.managers.node_manager import NodeManager
+
+            parameter_output_values, unique_uuid_to_values = NodeManager.serialize_parameter_output_values(
+                current_node, use_pickling=context.pickle_control_flow_result
+            )
             GriptapeNodes.EventManager().put_event(
                 ExecutionGriptapeNodeEvent(
                     wrapped_event=ExecutionEvent(
                         payload=ControlFlowResolvedEvent(
                             end_node_name=current_node.name,
-                            parameter_output_values=TypeValidator.safe_serialize(current_node.parameter_output_values),
+                            parameter_output_values=parameter_output_values,
+                            unique_parameter_uuid_to_values=unique_uuid_to_values if unique_uuid_to_values else None,
                         )
                     )
                 )
@@ -239,12 +271,17 @@ class CompleteState(State):
 
 # MACHINE TIME!!!
 class ControlFlowMachine(FSM[ControlFlowContext]):
-    def __init__(self, flow_name: str) -> None:
+    def __init__(self, flow_name: str, *, pickle_control_flow_result: bool = False) -> None:
         execution_type = GriptapeNodes.ConfigManager().get_config_value(
             "workflow_execution_mode", default=WorkflowExecutionMode.SEQUENTIAL
         )
         max_nodes_in_parallel = GriptapeNodes.ConfigManager().get_config_value("max_nodes_in_parallel", default=5)
-        context = ControlFlowContext(flow_name, max_nodes_in_parallel, execution_type=execution_type)
+        context = ControlFlowContext(
+            flow_name,
+            max_nodes_in_parallel,
+            execution_type=execution_type,
+            pickle_control_flow_result=pickle_control_flow_result,
+        )
         super().__init__(context)
 
     async def start_flow(self, start_node: BaseNode, debug_mode: bool = False) -> None:  # noqa: FBT001, FBT002
@@ -346,6 +383,10 @@ class ControlFlowMachine(FSM[ControlFlowContext]):
                 flow_manager.global_flow_queue.queue.remove(item)
         return start_nodes
 
+    async def cancel_flow(self) -> None:
+        """Cancel all nodes in the flow by delegating to the resolution machine."""
+        await self.resolution_machine.cancel_all_nodes()
+
     def reset_machine(self, *, cancel: bool = False) -> None:
         self._context.reset(cancel=cancel)
         self._current_state = None