griptape-nodes 0.65.5__py3-none-any.whl → 0.66.0__py3-none-any.whl

griptape_nodes/drivers/storage/local_storage_driver.py

@@ -6,6 +6,8 @@ from urllib.parse import urljoin
 import httpx
 
 from griptape_nodes.drivers.storage.base_storage_driver import BaseStorageDriver, CreateSignedUploadUrlResponse
+from griptape_nodes.retained_mode.events.os_events import ExistingFilePolicy, WriteFileRequest
+from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
 logger = logging.getLogger("griptape_nodes")
 
@@ -38,24 +40,59 @@ class LocalStorageDriver(BaseStorageDriver):
         else:
             self.base_url = base_url
 
-    def create_signed_upload_url(self, path: Path) -> CreateSignedUploadUrlResponse:
+    def create_signed_upload_url(
+        self, path: Path, existing_file_policy: ExistingFilePolicy = ExistingFilePolicy.OVERWRITE
+    ) -> CreateSignedUploadUrlResponse:
+        # on_write_file_request seems to work most reliably with an absolute path.
+        absolute_path = path if path.is_absolute() else self.workspace_directory / path
+
+        # Always delegate to OSManager for file path resolution and policy handling.
+        # Creating an empty file before the upload url gives us a chance to claim ownership
+        # of that particular file when creating the upload url. The file policy is not
+        # checked when actually uploading the file, it will always overwrite.
+        os_manager = GriptapeNodes.OSManager()
+        write_request = WriteFileRequest(
+            file_path=str(absolute_path),
+            content=b"",  # Empty content for URL generation
+            existing_file_policy=existing_file_policy,
+        )
+        result = os_manager.on_write_file_request(write_request)
+
+        if not result.succeeded():
+            msg = f"WriteFileRequest failed: {result.result_details}"
+            raise FileExistsError(msg)
+
+        # Use the resolved filename from OSManager
+        # Type checker: result is WriteFileResultSuccess when succeeded() is True
+        resolved_path = Path(result.final_file_path)  # type: ignore[attr-defined]
+
+        # WriteFileRequest always returns an absolute path, but the url needs
+        # to be workspace relative if passed in path was workspace relative.
+        if not path.is_absolute():
+            resolved_path = resolved_path.relative_to(self.workspace_directory)
+
         static_url = urljoin(self.base_url, "/static-upload-urls")
         try:
-            response = httpx.post(static_url, json={"file_path": str(path)})
+            response = httpx.post(static_url, json={"file_path": str(resolved_path)})
             response.raise_for_status()
         except httpx.HTTPStatusError as e:
-            msg = f"Failed to create upload URL for file {path}: {e}"
+            msg = f"Failed to create upload URL for file {resolved_path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
 
         response_data = response.json()
         url = response_data.get("url")
         if url is None:
-            msg = f"Failed to get upload URL for file {path}: {response_data}"
+            msg = f"Failed to get upload URL for file {resolved_path}: {response_data}"
             logger.error(msg)
             raise ValueError(msg)
 
-        return {"url": url, "headers": response_data.get("headers", {}), "method": "PUT"}
+        return {
+            "url": url,
+            "headers": response_data.get("headers", {}),
+            "method": "PUT",
+            "file_path": str(resolved_path),
+        }
 
     def create_signed_download_url(self, path: Path) -> str:
         # The base_url already includes the /static path, so just append the path

griptape_nodes/exe_types/base_iterative_nodes.py

@@ -108,7 +108,6 @@ class BaseIterativeStartNode(BaseNode):
     _current_iteration_count: int
     _total_iterations: int
     _flow: ControlFlow | None = None
-    is_parallel: bool = False  # Sequential by default
 
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
         super().__init__(name, metadata)

griptape_nodes/exe_types/connections.py

@@ -403,3 +403,45 @@ class Connections:
                 for conn_id in connection_ids:
                     connections.append(self.connections[conn_id])  # noqa: PERF401, Keeping loop for understanding.
         return connections
+
+    def is_node_in_forward_control_path(
+        self, start_node: BaseNode, target_node: BaseNode, visited: set[str] | None = None
+    ) -> bool:
+        """Check if target_node is reachable from start_node through control flow connections.
+
+        Args:
+            start_node: The node to start traversal from
+            target_node: The node to check if reachable
+            visited: Set of already visited node names (used internally for recursion)
+
+        Returns:
+            True if target_node is in the forward control path from start_node, False otherwise
+        """
+        if visited is None:
+            visited = set()
+
+        if start_node.name in visited:
+            return False
+        visited.add(start_node.name)
+
+        # Check ALL outgoing control connections
+        # This handles IfElse nodes that have multiple possible control outputs
+        if start_node.name in self.outgoing_index:
+            for param_name, connection_ids in self.outgoing_index[start_node.name].items():
+                # Find the parameter to check if it's a control type
+                param = start_node.get_parameter_by_name(param_name)
+                if param and param.output_type == ParameterTypeBuiltin.CONTROL_TYPE.value:
+                    # This is a control parameter - check all its connections
+                    for connection_id in connection_ids:
+                        if connection_id in self.connections:
+                            connection = self.connections[connection_id]
+                            next_node = connection.target_node
+
+                            if next_node.name == target_node.name:
+                                return True
+
+                            # Recursively check the forward path
+                            if self.is_node_in_forward_control_path(next_node, target_node, visited):
+                                return True
+
+        return False

griptape_nodes/exe_types/core_types.py

@@ -1967,7 +1967,7 @@ class ParameterContainer(Parameter, ABC):
         converters: list[Callable[[Any], Any]] | None = None,
         validators: list[Callable[[Parameter, Any], None]] | None = None,
         *,
-        hide: bool = False,
+        hide: bool | None = None,
         settable: bool = True,
         user_defined: bool = False,
         element_id: str | None = None,
@@ -2037,7 +2037,7 @@ class ParameterList(ParameterContainer):
         converters: list[Callable[[Any], Any]] | None = None,
         validators: list[Callable[[Parameter, Any], None]] | None = None,
         *,
-        hide: bool = False,
+        hide: bool | None = None,
         settable: bool = True,
         user_defined: bool = False,
         element_id: str | None = None,

griptape_nodes/exe_types/node_groups/__init__.py

@@ -1,6 +1,7 @@
 """Node group implementations for managing collections of nodes."""
 
+from .base_iterative_node_group import BaseIterativeNodeGroup
 from .base_node_group import BaseNodeGroup
 from .subflow_node_group import SubflowNodeGroup
 
-__all__ = ["BaseNodeGroup", "SubflowNodeGroup"]
+__all__ = ["BaseIterativeNodeGroup", "BaseNodeGroup", "SubflowNodeGroup"]

griptape_nodes/exe_types/node_groups/base_iterative_node_group.py

@@ -0,0 +1,177 @@
+"""Base class for iterative node groups (ForEach, ForLoop, etc.)."""
+
+from __future__ import annotations
+
+import logging
+from abc import abstractmethod
+from typing import Any
+
+from griptape_nodes.exe_types.core_types import (
+    Parameter,
+    ParameterMode,
+    ParameterTypeBuiltin,
+)
+from griptape_nodes.exe_types.node_groups.subflow_node_group import SubflowNodeGroup
+
+logger = logging.getLogger("griptape_nodes")
+
+
+class BaseIterativeNodeGroup(SubflowNodeGroup):
+    """Base class for iterative node groups (ForEach, ForLoop, etc.).
+
+    Combines the functionality of BaseIterativeStartNode and BaseIterativeEndNode
+    into a single group node that encapsulates the loop body as child nodes.
+
+    This provides a simpler user experience than separate start/end nodes while
+    maintaining the same execution capabilities (sequential/parallel, local/private/cloud).
+
+    The NodeExecutor detects instances of this class and handles iteration execution
+    via handle_iterative_group_execution(), similar to how it handles BaseIterativeEndNode.
+
+    Subclasses must implement:
+        - _get_iteration_items(): Return the list of items to iterate over
+        - _get_current_item_value(iteration_index): Get the value for current iteration
+    """
+
+    # Iteration state
+    _items: list[Any]
+    _current_iteration_count: int
+    _total_iterations: int
+    is_parallel: bool
+
+    # Results storage
+    _results_list: list[Any]
+
+    def __init__(
+        self,
+        name: str,
+        metadata: dict[Any, Any] | None = None,
+    ) -> None:
+        super().__init__(name, metadata)
+
+        # Initialize iteration state
+        self._items = []
+        self._current_iteration_count = 0
+        self._total_iterations = 0
+        self.is_parallel = False
+        self._results_list = []
+
+        # Add parallel execution control parameter
+        self.run_in_order = Parameter(
+            name="run_in_order",
+            tooltip="Execute all iterations in order or concurrently",
+            type=ParameterTypeBuiltin.BOOL.value,
+            allowed_modes={ParameterMode.PROPERTY},
+            default_value=True,
+            ui_options={"display_name": "Run in Order"},
+        )
+        self.add_parameter(self.run_in_order)
+
+        # Index parameter - available in all iterative nodes (left side - feeds into group)
+        self.index_param = Parameter(
+            name="index",
+            tooltip="Current index of the iteration",
+            type=ParameterTypeBuiltin.INT.value,
+            allowed_modes={ParameterMode.OUTPUT},
+            settable=False,
+            default_value=0,
+        )
+        self.add_parameter(self.index_param)
+
+        # Track left parameters for UI layout
+        if "left_parameters" not in self.metadata:
+            self.metadata["left_parameters"] = []
+        self.metadata["left_parameters"].append("index")
+
+        # Results collection parameters (right side - collects from group)
+        self.new_item_to_add = Parameter(
+            name="new_item_to_add",
+            tooltip="Item to add to results list for each iteration",
+            type=ParameterTypeBuiltin.ANY.value,
+            allowed_modes={ParameterMode.INPUT},
+        )
+        self.add_parameter(self.new_item_to_add)
+
+        self.results = Parameter(
+            name="results",
+            tooltip="Collected results from all iterations",
+            output_type="list",
+            allowed_modes={ParameterMode.OUTPUT},
+        )
+        self.add_parameter(self.results)
+
+        # Track right parameters for UI layout
+        if "right_parameters" not in self.metadata:
+            self.metadata["right_parameters"] = []
+        self.metadata["right_parameters"].extend(["new_item_to_add", "results"])
+
+    def after_value_set(self, parameter: Parameter, value: Any) -> None:
+        """Handle parameter value changes."""
+        super().after_value_set(parameter, value)
+        if parameter == self.run_in_order:
+            self.is_parallel = not value
+
+    @abstractmethod
+    def _get_iteration_items(self) -> list[Any]:
+        """Get the list of items to iterate over.
+
+        Returns:
+            List of items for iteration. Empty list if no items.
+        """
+
+    @abstractmethod
+    def _get_current_item_value(self, iteration_index: int) -> Any:
+        """Get the value for a specific iteration.
+
+        Args:
+            iteration_index: 0-based iteration index
+
+        Returns:
+            The value to use for this iteration
+        """
+
+    def _initialize_iteration_data(self) -> None:
+        """Initialize iteration-specific data and state."""
+        self._items = self._get_iteration_items()
+        self._total_iterations = len(self._items) if self._items else 0
+        self._current_iteration_count = 0
+        self._results_list = []
+
+    def _get_total_iterations(self) -> int:
+        """Return the total number of iterations for this loop."""
+        return self._total_iterations
+
+    def get_all_iteration_values(self) -> list[int]:
+        """Calculate and return all iteration index values.
+
+        For ForEach nodes, this returns indices 0, 1, 2, ...
+        For ForLoop nodes, this could return actual loop values.
+
+        Returns:
+            List of integer values for each iteration
+        """
+        return list(range(self._get_total_iterations()))
+
+    def _output_results_list(self) -> None:
+        """Output the current results list to the results parameter."""
+        import copy
+
+        self.parameter_output_values["results"] = copy.deepcopy(self._results_list)
+
+    def reset_for_workflow_run(self) -> None:
+        """Reset state for a fresh workflow run."""
+        self._results_list = []
+        self._current_iteration_count = 0
+        self._total_iterations = 0
+        self._output_results_list()
+
+    async def aprocess(self) -> None:
+        """Execute the iterative node group.
+
+        Note: This method is typically not called directly. The NodeExecutor
+        detects BaseIterativeNodeGroup instances and calls handle_iterative_group_execution()
+        instead. This implementation exists as a fallback for direct local execution.
+        """
+        # For direct local execution (when NodeExecutor doesn't intercept),
+        # just execute the subflow once. The NodeExecutor handles iteration logic.
+        await self.execute_subflow()

griptape_nodes/exe_types/node_groups/base_node_group.py

@@ -29,3 +29,4 @@ class BaseNodeGroup(BaseNode):
         super().__init__(name, metadata)
         self.nodes = {}
         self.metadata["is_node_group"] = True
+        self.metadata["executable"] = False

griptape_nodes/exe_types/node_groups/subflow_node_group.py

@@ -14,6 +14,7 @@ from griptape_nodes.exe_types.core_types import (
 from griptape_nodes.exe_types.node_groups.base_node_group import BaseNodeGroup
 from griptape_nodes.exe_types.node_types import (
     LOCAL_EXECUTION,
+    PRIVATE_EXECUTION,
     get_library_names_with_publish_handlers,
 )
 from griptape_nodes.retained_mode.events.connection_events import (
@@ -76,6 +77,7 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
             "start_flow_node": "StartFlow",
             "parameter_names": {},
         }
+        self.metadata["executable"] = True
 
         # Don't create subflow in __init__ - it will be created on-demand when nodes are added
         # or restored during deserialization
@@ -298,6 +300,26 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
 
         return proxy_param
 
+    def add_parameter_to_group_settings(self, parameter: Parameter) -> None:
+        """Add a parameter to the Group settings panel.
+
+        Args:
+            parameter: The parameter to add to settings
+        """
+        if ParameterMode.PROPERTY not in parameter.allowed_modes:
+            msg = f"Parameter '{parameter.name}' must allow PROPERTY mode to be added to settings."
+            raise ValueError(msg)
+
+        execution_environment: dict = self.metadata.get("execution_environment", {})
+        if LOCAL_EXECUTION not in execution_environment:
+            execution_environment[LOCAL_EXECUTION] = {"parameter_names": []}
+        if PRIVATE_EXECUTION not in execution_environment:
+            execution_environment[PRIVATE_EXECUTION] = {"parameter_names": []}
+
+        for library in execution_environment:
+            parameter_names = self.metadata["execution_environment"][library].get("parameter_names", [])
+            self.metadata["execution_environment"][library]["parameter_names"] = [parameter.name, *parameter_names]
+
     def get_all_nodes(self) -> dict[str, BaseNode]:
         all_nodes = {}
         for node_name, node in self.nodes.items():
@@ -945,15 +967,26 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
 
         Can be called by concrete subclasses in their aprocess() implementation.
         """
-        from griptape_nodes.retained_mode.events.execution_events import StartLocalSubflowRequest
+        from griptape_nodes.retained_mode.events.execution_events import (
+            StartLocalSubflowRequest,
+            StartLocalSubflowResultFailure,
+        )
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
         subflow = self.metadata.get("subflow_name")
         if subflow is not None and isinstance(subflow, str):
-            await GriptapeNodes.FlowManager().on_start_local_subflow_request(
+            result = await GriptapeNodes.FlowManager().on_start_local_subflow_request(
                 StartLocalSubflowRequest(flow_name=subflow)
             )
 
+            if isinstance(result, StartLocalSubflowResultFailure):
+                logger.error("%s: %s", self.name, result.result_details)
+                # Clear partial outputs to prevent inconsistent state
+                self.parameter_output_values.clear()
+                # Re-raise the error message directly without wrapping
+                msg = result.result_details
+                raise RuntimeError(msg)
+
         # After subflow execution, collect output values from internal nodes
         # and set them on the NodeGroup's output (right) proxy parameters
         connections = GriptapeNodes.FlowManager().get_connections()

griptape_nodes/exe_types/param_types/parameter_audio.py

@@ -46,7 +46,7 @@ class ParameterAudio(Parameter):
         microphone_capture_audio: bool = False,
         edit_audio: bool = False,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/exe_types/param_types/parameter_bool.py

@@ -42,7 +42,7 @@ class ParameterBool(Parameter):
         on_label: str | None = None,
         off_label: str | None = None,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/exe_types/param_types/parameter_button.py

@@ -88,7 +88,7 @@ class ParameterButton(Parameter):
         on_click: Button.OnClickCallback | None = None,
         get_button_state: Button.GetButtonStateCallback | None = None,
         href: str | None = None,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = False,

griptape_nodes/exe_types/param_types/parameter_float.py

@@ -47,7 +47,7 @@ class ParameterFloat(ParameterNumber):
         max_val: float = 100,
         validate_min_max: bool = False,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/exe_types/param_types/parameter_image.py

@@ -46,7 +46,7 @@ class ParameterImage(Parameter):
         webcam_capture_image: bool = False,
         edit_mask: bool = False,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/exe_types/param_types/parameter_int.py

@@ -47,7 +47,7 @@ class ParameterInt(ParameterNumber):
         max_val: float = 100,
         validate_min_max: bool = False,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/exe_types/param_types/parameter_number.py

@@ -41,7 +41,7 @@ class ParameterNumber(Parameter):
         max_val: float = 100,
         validate_min_max: bool = False,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/exe_types/param_types/parameter_string.py

@@ -46,7 +46,7 @@ class ParameterString(Parameter):
         placeholder_text: str | None = None,
         is_full_width: bool = False,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/exe_types/param_types/parameter_three_d.py

@@ -44,7 +44,7 @@ class Parameter3D(Parameter):
         clickable_file_browser: bool = True,
         expander: bool = False,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/exe_types/param_types/parameter_video.py

@@ -46,7 +46,7 @@ class ParameterVideo(Parameter):
         webcam_capture_video: bool = False,
         edit_video: bool = False,
         accept_any: bool = True,
-        hide: bool = False,
+        hide: bool | None = None,
         hide_label: bool = False,
         hide_property: bool = False,
         allow_input: bool = True,

griptape_nodes/machines/control_flow.py

@@ -480,14 +480,15 @@ class ControlFlowMachine(FSM[ControlFlowContext]):
                     # Figure out which graph the data node belongs to, if it belongs to a graph.
                     for graph_start_node_name in dag_builder.graphs:
                         graph_start_node = node_manager.get_node_by_name(graph_start_node_name)
-                        correct_graph = flow_manager.is_node_connected(graph_start_node, node)
+                        # Get boundary nodes (empty list if not connected)
+                        boundary_nodes = flow_manager.is_node_connected(graph_start_node, node)
                         # This means this node is in the downstream connection of one of this graph.
-                        if correct_graph:
+                        if boundary_nodes:
                             # Is the node connected to a graph?
                             disconnected = False
                             if node.name not in dag_builder.start_node_candidates:
-                                dag_builder.start_node_candidates[node.name] = set()
-                            dag_builder.start_node_candidates[node.name].add(graph_start_node_name)
+                                dag_builder.start_node_candidates[node.name] = {}
+                            dag_builder.start_node_candidates[node.name][graph_start_node_name] = set(boundary_nodes)
                     if disconnected:
                         # If the node is not connected to any graph, we can add it as it's own graph here.
                         # It will not cause any overlapping confusion with existing graphs.