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

griptape_nodes/exe_types/node_groups/base_iterative_node_group.py

@@ -2,18 +2,35 @@
 
 from __future__ import annotations
 
-import logging
 from abc import abstractmethod
+from enum import StrEnum
 from typing import Any
 
 from griptape_nodes.exe_types.core_types import (
+    ControlParameterInput,
     Parameter,
     ParameterMode,
     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 IterationControlParam(StrEnum):
+    """Parameter names for iteration control on iterative node groups."""
+
+    LOOP_COMPLETE = "loop_complete"
+    SKIP_ITERATION = "skip_iteration"
+    BREAK_LOOP = "break_loop"
 
 
 class BaseIterativeNodeGroup(SubflowNodeGroup):
@@ -37,7 +54,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 +69,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",
@@ -83,7 +110,15 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
             self.metadata["left_parameters"] = []
         self.metadata["left_parameters"].append("index")
 
-        # Results collection parameters (right side - collects from group)
+        # Control input for loop completion (right side - primary loop completion path)
+        self.loop_complete = ControlParameterInput(
+            tooltip="Signal that this iteration is complete and continue to next iteration",
+            name=IterationControlParam.LOOP_COMPLETE.value,
+        )
+        self.loop_complete.ui_options = {"display_name": "Loop Complete"}
+        self.add_parameter(self.loop_complete)
+
+        # Data parameter for the item to add (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",
@@ -92,6 +127,21 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
         )
         self.add_parameter(self.new_item_to_add)
 
+        # Skip and Break control inputs (right side - for loop control)
+        self.skip_iteration = ControlParameterInput(
+            tooltip="Skip current item and continue to next iteration",
+            name=IterationControlParam.SKIP_ITERATION.value,
+        )
+        self.skip_iteration.ui_options = {"display_name": "Skip to Next Iteration"}
+        self.add_parameter(self.skip_iteration)
+
+        self.break_loop = ControlParameterInput(
+            tooltip="Break out of loop immediately",
+            name=IterationControlParam.BREAK_LOOP.value,
+        )
+        self.break_loop.ui_options = {"display_name": "Break Out of Loop"}
+        self.add_parameter(self.break_loop)
+
         self.results = Parameter(
             name="results",
             tooltip="Collected results from all iterations",
@@ -103,13 +153,34 @@ class BaseIterativeNodeGroup(SubflowNodeGroup):
         # 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"])
+        self.metadata["right_parameters"].extend(
+            [
+                IterationControlParam.LOOP_COMPLETE.value,
+                "new_item_to_add",
+                IterationControlParam.SKIP_ITERATION.value,
+                IterationControlParam.BREAK_LOOP.value,
+                "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
+        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)
+
+            # Hide or show skip/break controls based on execution mode
+            # Skip and Break are only supported in sequential mode (run_in_order=True)
+            if run_in_order:
+                # Show controls when running sequentially
+                self.show_parameter_by_name(self.skip_iteration.name)
+                self.show_parameter_by_name(self.break_loop.name)
+            else:
+                # Hide controls when running in parallel (not supported)
+                self.hide_parameter_by_name(self.skip_iteration.name)
+                self.hide_parameter_by_name(self.break_loop.name)
 
     @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/huggingface/huggingface_repo_variant_parameter.py

@@ -0,0 +1,152 @@
+"""HuggingFace parameter class that supports repo + variant/subfolder selection."""
+
+import logging
+from pathlib import Path
+
+from huggingface_hub.constants import HF_HUB_CACHE
+
+from griptape_nodes.exe_types.node_types import BaseNode
+from griptape_nodes.exe_types.param_components.huggingface.huggingface_model_parameter import HuggingFaceModelParameter
+
+logger = logging.getLogger("griptape_nodes")
+
+
+def _get_repo_cache_path(repo_id: str) -> Path | None:
+    """Get the cache path for a repo if it exists."""
+    cache_path = Path(HF_HUB_CACHE)
+    if not cache_path.exists():
+        return None
+
+    # Convert repo_id to cache folder format: owner/repo -> models--owner--repo
+    folder_name = f"models--{repo_id.replace('/', '--')}"
+    repo_path = cache_path / folder_name
+
+    if repo_path.exists():
+        return repo_path
+    return None
+
+
+def _get_snapshot_path(repo_path: Path) -> Path | None:
+    """Get the latest snapshot path for a repo."""
+    snapshots_dir = repo_path / "snapshots"
+    if not snapshots_dir.exists():
+        return None
+
+    snapshots = [p for p in snapshots_dir.iterdir() if p.is_dir()]
+    if not snapshots:
+        return None
+
+    # Return the most recent snapshot
+    return max(snapshots, key=lambda p: p.stat().st_mtime)
+
+
+def _list_variants_in_cache(repo_id: str, variants: list[str]) -> list[tuple[str, str, str]]:
+    """List (repo_id, variant, revision) tuples for variants that exist in cache.
+
+    Args:
+        repo_id: The HuggingFace repo ID (e.g., "Lightricks/LTX-2")
+        variants: List of variant/subfolder names to check for (e.g., ["ltx-2-19b-dev", "ltx-2-19b-dev-fp8"])
+
+    Returns:
+        List of (repo_id, variant, revision) tuples for variants found in cache
+    """
+    repo_path = _get_repo_cache_path(repo_id)
+    if repo_path is None:
+        return []
+
+    snapshot_path = _get_snapshot_path(repo_path)
+    if snapshot_path is None:
+        return []
+
+    revision = snapshot_path.name
+    results = []
+
+    for variant in variants:
+        # Check for variant as a directory (subfolder model structure)
+        variant_dir_path = snapshot_path / variant
+        if variant_dir_path.exists() and variant_dir_path.is_dir():
+            results.append((repo_id, variant, revision))
+            continue
+
+        # Check for variant as a .safetensors file (single-file model structure)
+        variant_file_path = snapshot_path / f"{variant}.safetensors"
+        if variant_file_path.exists() and variant_file_path.is_file():
+            results.append((repo_id, variant, revision))
+
+    return results
+
+
+class HuggingFaceRepoVariantParameter(HuggingFaceModelParameter):
+    """Parameter class for selecting a variant/subfolder within a HuggingFace repo.
+
+    Use this when a single repo contains multiple model variants as subfolders.
+    For example, Lightricks/LTX-2 contains:
+    - ltx-2-19b-dev
+    - ltx-2-19b-dev-fp8
+    - ltx-2-19b-dev-fp4
+    """
+
+    def __init__(
+        self,
+        node: BaseNode,
+        repo_id: str,
+        variants: list[str],
+        parameter_name: str = "model",
+    ):
+        """Initialize the parameter.
+
+        Args:
+            node: The node this parameter belongs to
+            repo_id: The HuggingFace repo ID (e.g., "Lightricks/LTX-2")
+            variants: List of variant/subfolder names (e.g., ["ltx-2-19b-dev", "ltx-2-19b-dev-fp8"])
+            parameter_name: Name of the parameter (default: "model")
+        """
+        super().__init__(node, parameter_name)
+        self._repo_id = repo_id
+        self._variants = variants
+        self.refresh_parameters()
+
+    @classmethod
+    def _repo_variant_to_key(cls, repo_id: str, variant: str) -> str:
+        """Convert repo_id and variant to a display key."""
+        return f"{repo_id}/{variant}"
+
+    @classmethod
+    def _key_to_repo_variant(cls, key: str) -> tuple[str, str]:
+        """Parse a display key back to repo_id and variant.
+
+        Key format: "owner/repo/variant"
+        """
+        parts = key.rsplit("/", 1)
+        if len(parts) == 2:  # noqa: PLR2004
+            return parts[0], parts[1]
+        # Fallback: treat entire key as repo_id with empty variant
+        return key, ""
+
+    def fetch_repo_revisions(self) -> list[tuple[str, str]]:
+        """Fetch available variants from cache.
+
+        Returns list of (display_key, revision) tuples where display_key is "repo_id/variant".
+        """
+        variant_revisions = _list_variants_in_cache(self._repo_id, self._variants)
+        return [
+            (self._repo_variant_to_key(repo_id, variant), revision) for repo_id, variant, revision in variant_revisions
+        ]
+
+    def get_download_commands(self) -> list[str]:
+        """Return download commands for the repo."""
+        return [f'huggingface-cli download "{self._repo_id}"']
+
+    def get_download_models(self) -> list[str]:
+        """Return list of model names for download."""
+        return [self._repo_id]
+
+    def get_repo_variant_revision(self) -> tuple[str, str, str]:
+        """Get the selected repo_id, variant, and revision.
+
+        Returns:
+            Tuple of (repo_id, variant, revision)
+        """
+        repo_key, revision = self.get_repo_revision()
+        repo_id, variant = self._key_to_repo_variant(repo_key)
+        return repo_id, variant, revision

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,