griptape-nodes 0.66.2__py3-none-any.whl → 0.67.0__py3-none-any.whl

griptape_nodes/common/node_executor.py

@@ -1772,6 +1772,12 @@ class NodeExecutor:
         Returns:
             The upstream value if criteria met, None otherwise
         """
+        # If upstream is a BaseIterativeNodeGroup (e.g., ForEach Group) that's currently executing,
+        # we need to trace through its proxy parameter to find the actual resolved source.
+        # This handles the case where: ExternalNode -> ForEachGroup.proxy_param -> InternalNode
+        if isinstance(upstream_node, BaseIterativeNodeGroup) and upstream_node.state != NodeResolutionState.RESOLVED:
+            return self._get_value_through_iterative_group_proxy(upstream_node, upstream_param, packaged_node_names)
+
         if upstream_node.state != NodeResolutionState.RESOLVED:
             return None
 
@@ -1783,6 +1789,77 @@ class NodeExecutor:
 
         return upstream_node.get_parameter_value(upstream_param.name)
 
+    def _get_value_through_iterative_group_proxy(
+        self,
+        iterative_group: BaseIterativeNodeGroup,
+        proxy_param: Any,
+        packaged_node_names: list[str],
+    ) -> Any | None:
+        """Trace through an iterative group's proxy parameter to get value from the actual resolved source.
+
+        When a packaged node inside a ForEach Group has an incoming connection from the group's
+        proxy parameter, we need to find the external node that connects TO that proxy parameter
+        and get the value from there.
+
+        Connection chain: ResolvedExternalNode -> IterativeGroup.proxy_param -> PackagedInternalNode
+        We want to get the value from ResolvedExternalNode.
+
+        Args:
+            iterative_group: The BaseIterativeNodeGroup with the proxy parameter
+            proxy_param: The proxy parameter on the iterative group
+            packaged_node_names: List of packaged node names to exclude
+
+        Returns:
+            The value from the resolved external source, or None if not found
+        """
+        flow_manager = GriptapeNodes.FlowManager()
+        connections = flow_manager.get_connections()
+
+        # Find the incoming connection TO the proxy parameter on the iterative group
+        # This will give us the actual external source node
+        incoming_to_proxy = connections.get_incoming_connections_to_parameter(iterative_group, proxy_param)
+
+        for conn in incoming_to_proxy:
+            # Skip internal connections (from nodes inside the group)
+            if conn.is_node_group_internal:
+                continue
+
+            source_node = conn.source_node
+            source_param = conn.source_parameter
+
+            # Skip if the source is also inside the packaged nodes
+            if source_node.name in packaged_node_names:
+                continue
+
+            # The source must be resolved for us to get its value
+            if source_node.state != NodeResolutionState.RESOLVED:
+                logger.debug(
+                    "Source node '%s' for proxy param '%s.%s' is not resolved (state: %s)",
+                    source_node.name,
+                    iterative_group.name,
+                    proxy_param.name,
+                    source_node.state,
+                )
+                continue
+
+            # Get the value from the resolved source node
+            if source_param.name in source_node.parameter_output_values:
+                value = source_node.parameter_output_values[source_param.name]
+            else:
+                value = source_node.get_parameter_value(source_param.name)
+
+            logger.debug(
+                "Traced through proxy: %s.%s -> %s.%s (value type: %s)",
+                source_node.name,
+                source_param.name,
+                iterative_group.name,
+                proxy_param.name,
+                type(value).__name__ if value is not None else "None",
+            )
+            return value
+
+        return None
+
     def _map_to_startflow_parameter(
         self,
         packaged_node_name: str,

griptape_nodes/exe_types/core_types.py

@@ -908,7 +908,15 @@ class DeprecationMessage(ParameterMessage):
 class ParameterGroup(BaseNodeElement, UIOptionsMixin):
     """UI element for a group of parameters."""
 
-    def __init__(self, name: str, ui_options: dict | None = None, *, collapsed: bool = False, **kwargs):
+    def __init__(
+        self,
+        name: str,
+        ui_options: dict | None = None,
+        *,
+        collapsed: bool = False,
+        user_defined: bool = False,
+        **kwargs,
+    ):
         super().__init__(name=name, **kwargs)
         if ui_options is None:
             ui_options = {}
@@ -920,6 +928,7 @@ class ParameterGroup(BaseNodeElement, UIOptionsMixin):
             ui_options["collapsed"] = collapsed
 
         self._ui_options = ui_options
+        self.user_defined = user_defined
 
     @property
     def ui_options(self) -> dict:
@@ -1181,6 +1190,7 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
     serializable: bool = True
 
     user_defined: bool = False
+    private: bool = False
     _allowed_modes: set = field(
         default_factory=lambda: {
             ParameterMode.OUTPUT,
@@ -1222,6 +1232,7 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         settable: bool = True,
         serializable: bool = True,
         user_defined: bool = False,
+        private: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
         parent_container_name: str | None = None,
@@ -1246,6 +1257,7 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         self._settable = settable
         self.serializable = serializable
         self.user_defined = user_defined
+        self.private = private
 
         # Process allowed_modes - use convenience parameters if allowed_modes not explicitly set
         if allowed_modes is None:
@@ -1401,6 +1413,7 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         our_dict["is_user_defined"] = self.user_defined
         our_dict["settable"] = self.settable
         our_dict["serializable"] = self.serializable
+        our_dict["private"] = self.private
         our_dict["ui_options"] = self.ui_options
 
         # Let's bundle up the mode details.
@@ -1838,6 +1851,7 @@ class ControlParameter(Parameter, ABC):
         ui_options: dict | None = None,
         *,
         user_defined: bool = False,
+        private: bool = False,
     ):
         # Call parent with a few explicit tweaks.
         super().__init__(
@@ -1857,6 +1871,7 @@ class ControlParameter(Parameter, ABC):
             validators=validators,
             ui_options=ui_options,
             user_defined=user_defined,
+            private=private,
             element_type=self.__class__.__name__,
         )
 
@@ -1875,6 +1890,7 @@ class ControlParameterInput(ControlParameter):
         validators: list[Callable[[Parameter, Any], None]] | None = None,
         *,
         user_defined: bool = False,
+        private: bool = False,
     ):
         allowed_modes = {ParameterMode.INPUT}
         input_types = [ParameterTypeBuiltin.CONTROL_TYPE.value]
@@ -1899,6 +1915,7 @@ class ControlParameterInput(ControlParameter):
             validators=validators,
             ui_options=ui_options,
             user_defined=user_defined,
+            private=private,
         )
 
 
@@ -1916,6 +1933,7 @@ class ControlParameterOutput(ControlParameter):
         validators: list[Callable[[Parameter, Any], None]] | None = None,
         *,
         user_defined: bool = False,
+        private: bool = False,
     ):
         allowed_modes = {ParameterMode.OUTPUT}
         output_type = ParameterTypeBuiltin.CONTROL_TYPE.value
@@ -1940,6 +1958,7 @@ class ControlParameterOutput(ControlParameter):
             validators=validators,
             ui_options=ui_options,
             user_defined=user_defined,
+            private=private,
         )
 
 
@@ -1970,6 +1989,7 @@ class ParameterContainer(Parameter, ABC):
         hide: bool | None = None,
         settable: bool = True,
         user_defined: bool = False,
+        private: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
     ):
@@ -1991,6 +2011,7 @@ class ParameterContainer(Parameter, ABC):
             hide=hide,
             settable=settable,
             user_defined=user_defined,
+            private=private,
             element_id=element_id,
             element_type=element_type,
         )
@@ -2040,6 +2061,7 @@ class ParameterList(ParameterContainer):
         hide: bool | None = None,
         settable: bool = True,
         user_defined: bool = False,
+        private: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
         max_items: int | None = None,
@@ -2080,6 +2102,7 @@ class ParameterList(ParameterContainer):
             hide=hide,
             settable=settable,
             user_defined=user_defined,
+            private=private,
             element_id=element_id,
             element_type=element_type,
         )
@@ -2418,6 +2441,7 @@ class ParameterKeyValuePair(Parameter):
         *,
         settable: bool = True,
         user_defined: bool = False,
+        private: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
     ):
@@ -2437,6 +2461,7 @@ class ParameterKeyValuePair(Parameter):
             validators=validators,
             settable=settable,
             user_defined=user_defined,
+            private=private,
             element_id=element_id,
             element_type=element_type,
         )
@@ -2538,6 +2563,7 @@ class ParameterDictionary(ParameterContainer):
         *,
         settable: bool = True,
         user_defined: bool = False,
+        private: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
     ):
@@ -2557,6 +2583,7 @@ class ParameterDictionary(ParameterContainer):
             validators=validators,
             settable=settable,
             user_defined=user_defined,
+            private=private,
             element_id=element_id,
             element_type=element_type,
         )

griptape_nodes/exe_types/node_groups/base_iterative_node_group.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import logging
 from abc import abstractmethod
 from typing import Any
 
@@ -12,8 +11,16 @@ from griptape_nodes.exe_types.core_types import (
     ParameterTypeBuiltin,
 )
 from griptape_nodes.exe_types.node_groups.subflow_node_group import SubflowNodeGroup
+from griptape_nodes.traits.options import Options
 
-logger = logging.getLogger("griptape_nodes")
+# Execution mode choices and their corresponding boolean values (True = run in order)
+EXECUTION_MODE_ONE_AT_A_TIME = "Run Group Items One at a Time"
+EXECUTION_MODE_ALL_AT_ONCE = "Run Group Items All at Once"
+EXECUTION_MODE_CHOICES = [EXECUTION_MODE_ONE_AT_A_TIME, EXECUTION_MODE_ALL_AT_ONCE]
+EXECUTION_MODE_VALUE_LOOKUP = {
+    EXECUTION_MODE_ONE_AT_A_TIME: True,
+    EXECUTION_MODE_ALL_AT_ONCE: False,
+}
 
 
 class BaseIterativeNodeGroup(SubflowNodeGroup):
@@ -37,7 +44,6 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
     _items: list[Any]
     _current_iteration_count: int
     _total_iterations: int
-    is_parallel: bool
 
     # Results storage
     _results_list: list[Any]
@@ -53,20 +59,31 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
         self._items = []
         self._current_iteration_count = 0
         self._total_iterations = 0
-        self.is_parallel = False
         self._results_list = []
 
-        # Add parallel execution control parameter
+        # Hidden boolean parameter used by node_executor for execution logic
         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"},
+            hide=True,
         )
         self.add_parameter(self.run_in_order)
 
+        # User selection that controls run_in_order
+        self.execution_mode = Parameter(
+            name="execution_mode",
+            tooltip="Execute all iterations in order or concurrently",
+            type=ParameterTypeBuiltin.STR.value,
+            allowed_modes={ParameterMode.PROPERTY},
+            default_value=EXECUTION_MODE_ONE_AT_A_TIME,
+            traits={Options(choices=EXECUTION_MODE_CHOICES, show_search=False)},
+            ui_options={"display_name": "Execution Mode"},
+        )
+        self.add_parameter(self.execution_mode)
+
         # Index parameter - available in all iterative nodes (left side - feeds into group)
         self.index_param = Parameter(
             name="index",
@@ -108,8 +125,10 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
     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
+        if parameter == self.execution_mode:
+            # Convert string choice to boolean and update run_in_order parameter
+            run_in_order = EXECUTION_MODE_VALUE_LOOKUP.get(value, True)
+            self.set_parameter_value("run_in_order", run_in_order)
 
     @abstractmethod
     def _get_iteration_items(self) -> list[Any]:

griptape_nodes/exe_types/node_groups/base_node_group.py

@@ -2,7 +2,15 @@ from __future__ import annotations
 
 from typing import Any
 
-from griptape_nodes.exe_types.node_types import BaseNode
+from griptape_nodes.exe_types.core_types import (
+    Parameter,
+    ParameterMode,
+)
+from griptape_nodes.exe_types.node_types import (
+    BaseNode,
+)
+
+GROUP_SETTINGS_PARAMS_METADATA_KEY = "group_settings_params"
 
 
 class BaseNodeGroup(BaseNode):
@@ -30,3 +38,58 @@ class BaseNodeGroup(BaseNode):
         self.nodes = {}
         self.metadata["is_node_group"] = True
         self.metadata["executable"] = False
+
+    def add_parameter_to_group_settings(self, parameter: Parameter) -> None:
+        """Add a parameter to the Group settings panel.
+
+        Group settings parameters are determined by metadata in the frontend.
+
+        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)
+
+        if GROUP_SETTINGS_PARAMS_METADATA_KEY not in self.metadata:
+            self.metadata[GROUP_SETTINGS_PARAMS_METADATA_KEY] = []
+
+        group_settings_params: list[str] = self.metadata.get(GROUP_SETTINGS_PARAMS_METADATA_KEY, [])
+        if parameter.name not in group_settings_params:
+            group_settings_params.append(parameter.name)
+            self.metadata[GROUP_SETTINGS_PARAMS_METADATA_KEY] = group_settings_params
+
+    def add_nodes_to_group(self, nodes: list[BaseNode]) -> None:
+        """Add nodes to this group.
+
+        Args:
+            nodes: A list of nodes to add to this group
+        """
+        for node in nodes:
+            self.nodes[node.name] = node
+
+        node_names_in_group = set(self.nodes.keys())
+        self.metadata["node_names_in_group"] = list(node_names_in_group)
+
+    def remove_nodes_from_group(self, nodes: list[BaseNode]) -> None:
+        """Remove nodes from this group.
+
+        Args:
+            nodes: A list of nodes to remove from this group
+        """
+        for node in nodes:
+            if node.name in self.nodes:
+                del self.nodes[node.name]
+
+    def _add_nodes_to_group_dict(self, nodes: list[BaseNode]) -> None:
+        """Add nodes to the group's node dictionary."""
+        for node in nodes:
+            node.parent_group = self
+            self.nodes[node.name] = node
+
+    def _validate_nodes_in_group(self, nodes: list[BaseNode]) -> None:
+        """Validate that all nodes are in the group."""
+        for node in nodes:
+            if node.name not in self.nodes:
+                msg = f"Node {node.name} is not in node group {self.name}"
+                raise ValueError(msg)

griptape_nodes/exe_types/node_groups/subflow_node_group.py

@@ -14,7 +14,6 @@ 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 (
@@ -300,26 +299,6 @@ 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():
@@ -478,12 +457,6 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
         for parent_group, node_list in child_nodes.items():
             parent_group.remove_nodes_from_group(node_list)
 
-    def _add_nodes_to_group_dict(self, nodes: list[BaseNode]) -> None:
-        """Add nodes to the group's node dictionary."""
-        for node in nodes:
-            node.parent_group = self
-            self.nodes[node.name] = node
-
     def _cleanup_proxy_parameter(self, proxy_parameter: Parameter, metadata_key: str) -> None:
         """Clean up proxy parameter if it has no more connections.
 
@@ -892,13 +865,6 @@ class SubflowNodeGroup(BaseNodeGroup, ABC):
         GriptapeNodes.handle_request(create_first_connection)
         GriptapeNodes.handle_request(create_second_connection)
 
-    def _validate_nodes_in_group(self, nodes: list[BaseNode]) -> None:
-        """Validate that all nodes are in the group."""
-        for node in nodes:
-            if node.name not in self.nodes:
-                msg = f"Node {node.name} is not in node group {self.name}"
-                raise ValueError(msg)
-
     def delete_nodes_from_group(self, nodes: list[BaseNode]) -> None:
         """Delete nodes from the group and untrack their connections.
 

griptape_nodes/exe_types/param_components/seed_parameter.py

@@ -6,8 +6,9 @@ from griptape_nodes.exe_types.node_types import BaseNode
 
 
 class SeedParameter:
-    def __init__(self, node: BaseNode):
+    def __init__(self, node: BaseNode, max_seed: int = 2**32 - 1) -> None:
         self._node = node
+        self._max_seed = max_seed
 
     def add_input_parameters(self) -> None:
         self._node.add_parameter(
@@ -51,7 +52,7 @@ class SeedParameter:
     def preprocess(self) -> None:
         if self._node.get_parameter_value("randomize_seed"):
             # Not using for cryptographic purposes
-            seed = random.randint(0, 2**32 - 1)  # noqa: S311
+            seed = random.randint(0, self._max_seed)  # noqa: S311
             self._node.set_parameter_value("seed", seed)
             self._node.publish_update_to_parameter("seed", seed)
 

griptape_nodes/exe_types/param_types/parameter_audio.py

@@ -55,6 +55,7 @@ class ParameterAudio(Parameter):
         settable: bool = True,
         serializable: bool = True,
         user_defined: bool = False,
+        private: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
         parent_container_name: str | None = None,
@@ -90,6 +91,7 @@ class ParameterAudio(Parameter):
             settable: Whether the parameter is settable
             serializable: Whether the parameter is serializable
             user_defined: Whether the parameter is user-defined
+            private: Whether this parameter is private
             element_id: Element ID
             element_type: Element type
             parent_container_name: Name of parent container
@@ -145,6 +147,7 @@ class ParameterAudio(Parameter):
             settable=settable,
             serializable=serializable,
             user_defined=user_defined,
+            private=private,
             element_id=element_id,
             element_type=element_type,
             parent_container_name=parent_container_name,

griptape_nodes/exe_types/param_types/parameter_bool.py

@@ -51,6 +51,7 @@ class ParameterBool(Parameter):
         settable: bool = True,
         serializable: bool = True,
         user_defined: bool = False,
+        private: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
         parent_container_name: str | None = None,
@@ -82,6 +83,7 @@ class ParameterBool(Parameter):
             settable: Whether the parameter is settable
             serializable: Whether the parameter is serializable
             user_defined: Whether the parameter is user-defined
+            private: Whether this parameter is private
             element_id: Element ID
             element_type: Element type
             parent_container_name: Name of parent container
@@ -136,6 +138,7 @@ class ParameterBool(Parameter):
             settable=settable,
             serializable=serializable,
             user_defined=user_defined,
+            private=private,
             element_id=element_id,
             element_type=element_type,
             parent_container_name=parent_container_name,

griptape_nodes/exe_types/param_types/parameter_button.py

@@ -97,6 +97,7 @@ class ParameterButton(Parameter):
         settable: bool = True,
         serializable: bool = True,
         user_defined: bool = False,
+        private: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
         parent_container_name: str | None = None,
@@ -139,6 +140,7 @@ class ParameterButton(Parameter):
             settable: Whether the parameter is settable
             serializable: Whether the parameter is serializable
             user_defined: Whether the parameter is user-defined
+            private: Whether this parameter is private
             element_id: Element ID
             element_type: Element type
             parent_container_name: Name of parent container
@@ -212,6 +214,7 @@ class ParameterButton(Parameter):
             settable=settable,
             serializable=serializable,
             user_defined=user_defined,
+            private=private,
             element_id=element_id,
             element_type=element_type,
             parent_container_name=parent_container_name,