griptape-nodes 0.59.2__py3-none-any.whl → 0.60.0__py3-none-any.whl

griptape_nodes/exe_types/core_types.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import logging
 import uuid
+import warnings
 from abc import ABC, abstractmethod
 from collections.abc import Callable
 from copy import deepcopy
@@ -923,6 +924,9 @@ class ParameterBase(BaseNodeElement, ABC):
 
 
 class Parameter(BaseNodeElement, UIOptionsMixin):
+    # Maximum number of input types to show in tooltip before truncating
+    _MAX_TOOLTIP_INPUT_TYPES = 3
+
     # This is the list of types that the Parameter can accept, either externally or when internally treated as a property.
     # Today, we can accept multiple types for input, but only a single output type.
     tooltip: str | list[dict]  # Default tooltip, can be string or list of dicts
@@ -956,11 +960,12 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
     next: Parameter | None = None
     prev: Parameter | None = None
     parent_container_name: str | None = None
+    parent_element_name: str | None = None
 
-    def __init__(  # noqa: PLR0913,PLR0912
+    def __init__(  # noqa: C901, PLR0912, PLR0913, PLR0915
         self,
         name: str,
-        tooltip: str | list[dict],
+        tooltip: str | list[dict] | None = None,
         type: str | None = None,  # noqa: A002
         input_types: list[str] | None = None,
         output_type: str | None = None,
@@ -974,12 +979,19 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         traits: set[Trait.__class__ | Trait] | None = None,  # We are going to make these children.
         ui_options: dict | None = None,
         *,
+        hide: bool = False,
+        hide_label: bool = False,
+        hide_property: bool = False,
+        allow_input: bool = True,
+        allow_property: bool = True,
+        allow_output: bool = True,
         settable: bool = True,
         serializable: bool = True,
         user_defined: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
         parent_container_name: str | None = None,
+        parent_element_name: str | None = None,
     ):
         if not element_id:
             element_id = str(uuid.uuid4().hex)
@@ -987,6 +999,11 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
             element_type = self.__class__.__name__
         super().__init__(element_id=element_id, element_type=element_type)
         self.name = name
+
+        # Generate default tooltip if none provided
+        if not tooltip:
+            tooltip = self._generate_default_tooltip(name, type, input_types, output_type)
+
         self.tooltip = tooltip
         self.default_value = default_value
         self.tooltip_as_input = tooltip_as_input
@@ -995,11 +1012,37 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         self._settable = settable
         self.serializable = serializable
         self.user_defined = user_defined
+
+        # Process allowed_modes - use convenience parameters if allowed_modes not explicitly set
         if allowed_modes is None:
-            self._allowed_modes = {ParameterMode.INPUT, ParameterMode.OUTPUT, ParameterMode.PROPERTY}
+            self._allowed_modes = set()
+            if allow_input:
+                self._allowed_modes.add(ParameterMode.INPUT)
+            if allow_property:
+                self._allowed_modes.add(ParameterMode.PROPERTY)
+            if allow_output:
+                self._allowed_modes.add(ParameterMode.OUTPUT)
         else:
             self._allowed_modes = allowed_modes
 
+            # Warn if both allowed_modes and convenience parameters are set
+            convenience_params_used = []
+            if not allow_input:
+                convenience_params_used.append("allow_input=False")
+            if not allow_property:
+                convenience_params_used.append("allow_property=False")
+            if not allow_output:
+                convenience_params_used.append("allow_output=False")
+
+            if convenience_params_used:
+                warnings.warn(
+                    f"Parameter '{name}': Both 'allowed_modes' and convenience parameters "
+                    f"({', '.join(convenience_params_used)}) are set. Using 'allowed_modes' "
+                    f"and ignoring convenience parameters.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+
         if converters is None:
             self._converters = []
         else:
@@ -1009,10 +1052,20 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
             self._validators = []
         else:
             self._validators = validators
+
+        # Process common UI options from constructor parameters
         if ui_options is None:
             self._ui_options = {}
         else:
-            self._ui_options = ui_options
+            self._ui_options = ui_options.copy()
+
+        # Add common UI options if they have truthy values
+        if hide:
+            self._ui_options["hide"] = hide
+        if hide_label:
+            self._ui_options["hide_label"] = hide_label
+        if hide_property:
+            self._ui_options["hide_property"] = hide_property
         if traits:
             for trait in traits:
                 if not isinstance(trait, Trait):
@@ -1026,6 +1079,62 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         self.input_types = input_types
         self.output_type = output_type
         self.parent_container_name = parent_container_name
+        self.parent_element_name = parent_element_name
+
+    def _generate_default_tooltip(
+        self,
+        name: str,
+        type: str | None,  # noqa: A002
+        input_types: list[str] | None,
+        output_type: str | None,
+    ) -> str:
+        """Generate a default tooltip describing the parameter type and usage.
+
+        Args:
+            name: The parameter name
+            type: The parameter type
+            input_types: List of accepted input types
+            output_type: The output type
+
+        Returns:
+            A descriptive tooltip string
+        """
+        # Determine the primary type to describe
+        primary_type = type
+        if not primary_type and input_types:
+            primary_type = input_types[0]
+        if not primary_type and output_type:
+            primary_type = output_type
+        if not primary_type:
+            primary_type = "any"
+
+        # Create a human-readable description
+        type_descriptions = {
+            "str": "text/string",
+            "bool": "boolean (true/false)",
+            "int": "integer number",
+            "float": "decimal number",
+            "any": "any type of data",
+            "list": "list/array",
+            "dict": "dictionary/object",
+            "parametercontroltype": "control flow",
+        }
+
+        type_desc = type_descriptions.get(primary_type.lower(), primary_type)
+
+        # Build the tooltip
+        tooltip_parts = [f"Enter {type_desc} for {name}"]
+
+        # Add input type info if different from primary type
+        if input_types and len(input_types) > 1:
+            input_desc = ", ".join(
+                type_descriptions.get(t.lower(), t) for t in input_types[: self._MAX_TOOLTIP_INPUT_TYPES]
+            )
+            if len(input_types) > self._MAX_TOOLTIP_INPUT_TYPES:
+                input_desc += f" or {len(input_types) - self._MAX_TOOLTIP_INPUT_TYPES} other types"
+            tooltip_parts.append(f"Accepts: {input_desc}")
+
+        return ". ".join(tooltip_parts) + "."
 
     def to_dict(self) -> dict[str, Any]:
         """Returns a nested dictionary representation of this node and its children."""
@@ -1055,6 +1164,8 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
         our_dict["mode_allowed_property"] = allows_property
         our_dict["mode_allowed_output"] = allows_output
         our_dict["parent_container_name"] = self.parent_container_name
+        our_dict["parent_element_name"] = self.parent_element_name
+        our_dict["parent_group_name"] = self.parent_group_name
 
         return our_dict
 
@@ -1156,6 +1267,132 @@ class Parameter(BaseNodeElement, UIOptionsMixin):
     def ui_options(self, value: dict) -> None:
         self._ui_options = value
 
+    @property
+    def hide(self) -> bool:
+        """Get whether the entire parameter is hidden in the UI.
+
+        Returns:
+            True if the parameter should be hidden, False otherwise
+        """
+        return self.ui_options.get("hide", False)
+
+    @hide.setter
+    @BaseNodeElement.emits_update_on_write
+    def hide(self, value: bool) -> None:
+        """Set whether to hide the entire parameter in the UI.
+
+        Args:
+            value: True to hide the parameter, False to show it
+        """
+        self.update_ui_options_key("hide", value)
+
+    @property
+    def hide_label(self) -> bool:
+        """Get whether the parameter label is hidden in the UI.
+
+        Returns:
+            True if the label should be hidden, False otherwise
+        """
+        return self.ui_options.get("hide_label", False)
+
+    @hide_label.setter
+    @BaseNodeElement.emits_update_on_write
+    def hide_label(self, value: bool) -> None:
+        """Set whether to hide the parameter label in the UI.
+
+        Args:
+            value: True to hide the label, False to show it
+        """
+        self.update_ui_options_key("hide_label", value)
+
+    @property
+    def hide_property(self) -> bool:
+        """Get whether the parameter is hidden in property mode.
+
+        Returns:
+            True if the parameter should be hidden in property mode, False otherwise
+        """
+        return self.ui_options.get("hide_property", False)
+
+    @hide_property.setter
+    @BaseNodeElement.emits_update_on_write
+    def hide_property(self, value: bool) -> None:
+        """Set whether to hide the parameter in property mode.
+
+        Args:
+            value: True to hide in property mode, False to show it
+        """
+        self.update_ui_options_key("hide_property", value)
+
+    @property
+    def allow_input(self) -> bool:
+        """Get whether the parameter allows INPUT mode.
+
+        Returns:
+            True if INPUT mode is allowed, False otherwise
+        """
+        return ParameterMode.INPUT in self.allowed_modes
+
+    @allow_input.setter
+    def allow_input(self, value: bool) -> None:
+        """Set whether to allow INPUT mode.
+
+        Args:
+            value: True to allow INPUT mode, False to disallow it
+        """
+        current_modes = self.allowed_modes.copy()
+        if value:
+            current_modes.add(ParameterMode.INPUT)
+        else:
+            current_modes.discard(ParameterMode.INPUT)
+        self.allowed_modes = current_modes
+
+    @property
+    def allow_property(self) -> bool:
+        """Get whether the parameter allows PROPERTY mode.
+
+        Returns:
+            True if PROPERTY mode is allowed, False otherwise
+        """
+        return ParameterMode.PROPERTY in self.allowed_modes
+
+    @allow_property.setter
+    def allow_property(self, value: bool) -> None:
+        """Set whether to allow PROPERTY mode.
+
+        Args:
+            value: True to allow PROPERTY mode, False to disallow it
+        """
+        current_modes = self.allowed_modes.copy()
+        if value:
+            current_modes.add(ParameterMode.PROPERTY)
+        else:
+            current_modes.discard(ParameterMode.PROPERTY)
+        self.allowed_modes = current_modes
+
+    @property
+    def allow_output(self) -> bool:
+        """Get whether the parameter allows OUTPUT mode.
+
+        Returns:
+            True if OUTPUT mode is allowed, False otherwise
+        """
+        return ParameterMode.OUTPUT in self.allowed_modes
+
+    @allow_output.setter
+    def allow_output(self, value: bool) -> None:
+        """Set whether to allow OUTPUT mode.
+
+        Args:
+            value: True to allow OUTPUT mode, False to disallow it
+        """
+        current_modes = self.allowed_modes.copy()
+        if value:
+            current_modes.add(ParameterMode.OUTPUT)
+        else:
+            current_modes.discard(ParameterMode.OUTPUT)
+        self.allowed_modes = current_modes
+
     @property
     def input_types(self) -> list[str]:
         return self._custom_getter_for_property_input_types()

griptape_nodes/exe_types/node_types.py

@@ -458,7 +458,13 @@ class BaseNode(ABC):
         if self.does_name_exist(param.name):
             msg = f"Cannot have duplicate names on parameters. Encountered two instances of '{param.name}'."
             raise ValueError(msg)
-        self.add_node_element(param)
+        parameter_group = (
+            self.get_group_by_name_or_element_id(param.parent_element_name) if param.parent_element_name else None
+        )
+        if parameter_group is not None:
+            parameter_group.add_child(param)
+        else:
+            self.add_node_element(param)
         self._emit_parameter_lifecycle_event(param)
 
     def remove_parameter_element_by_name(self, element_name: str) -> None:

griptape_nodes/exe_types/param_components/huggingface/__init__.py

@@ -0,0 +1 @@
+"""Reusable HuggingFace parameters."""

griptape_nodes/exe_types/param_components/huggingface/huggingface_model_parameter.py

@@ -0,0 +1,168 @@
+import logging
+import re
+from abc import ABC, abstractmethod
+
+from griptape_nodes.exe_types.core_types import Parameter, ParameterMessage, ParameterMode
+from griptape_nodes.exe_types.node_types import BaseNode
+from griptape_nodes.traits.options import Options
+
+logger = logging.getLogger("griptape_nodes")
+
+
+class HuggingFaceModelParameter(ABC):
+    @classmethod
+    def _repo_revision_to_key(cls, repo_revision: tuple[str, str]) -> str:
+        return f"{repo_revision[0]} ({repo_revision[1]})"
+
+    @classmethod
+    def _key_to_repo_revision(cls, key: str) -> tuple[str, str]:
+        # Check if key has hash format using regex
+        hash_pattern = r"^(.+) \(([a-f0-9]{40})\)$"
+        match = re.match(hash_pattern, key)
+        if match:
+            return match.group(1), match.group(2)
+
+        # Key is just the model name (no hash)
+        return key, ""
+
+    def __init__(self, node: BaseNode, parameter_name: str):
+        self._node = node
+        self._parameter_name = parameter_name
+        self._repo_revisions = []
+
+    def refresh_parameters(self) -> None:
+        parameter = self._node.get_parameter_by_name(self._parameter_name)
+        if parameter is None:
+            logger.debug(
+                "Parameter '%s' not found on node '%s'; cannot refresh choices.",
+                self._parameter_name,
+                self._node.name,
+            )
+            return
+
+        choices = self.get_choices()
+
+        current_value = self._node.get_parameter_value(self._parameter_name)
+        if current_value in choices:
+            default_value = current_value
+        else:
+            default_value = choices[0]
+
+        if parameter.find_elements_by_type(Options):
+            self._node._update_option_choices(self._parameter_name, choices, default_value)
+        else:
+            parameter.add_trait(Options(choices=choices))
+
+    def add_input_parameters(self) -> None:
+        choices = self.get_choices()
+
+        if not choices:
+            self._node.add_node_element(
+                ParameterMessage(
+                    name=f"huggingface_repo_parameter_message_{self._parameter_name}",
+                    title="Huggingface Model Download Required",
+                    variant="warning",
+                    value=self.get_help_message(),
+                    button_link=f"#model-management?search={self.get_download_models()[0]}",
+                    button_text="Model Management",
+                    button_icon="hard-drive",
+                )
+            )
+            return
+
+        self._node.add_parameter(
+            Parameter(
+                name=self._parameter_name,
+                default_value=choices[0] if choices else None,
+                input_types=["str"],
+                type="str",
+                ui_options={"display_name": self._parameter_name, "show_search": True},
+                traits={
+                    Options(
+                        choices=choices,
+                    )
+                },
+                tooltip=self._parameter_name,
+                allowed_modes={ParameterMode.PROPERTY},
+            )
+        )
+
+    def remove_input_parameters(self) -> None:
+        self._node.remove_parameter_element_by_name(self._parameter_name)
+        self._node.remove_parameter_element_by_name(f"huggingface_repo_parameter_message_{self._parameter_name}")
+
+    def get_choices(self) -> list[str]:
+        # Ensure the latest repo revisions are fetched
+        self._repo_revisions = self.fetch_repo_revisions()
+        # Count occurrences of each model name
+        model_counts = {}
+        for repo_id, _ in self.list_repo_revisions():
+            model_counts[repo_id] = model_counts.get(repo_id, 0) + 1
+
+        # Generate choices with hash only when there are duplicates
+        choices = []
+        for repo_revision in self.list_repo_revisions():
+            repo_id, _ = repo_revision
+            if model_counts[repo_id] > 1:
+                # Multiple versions exist, show hash for disambiguation
+                choices.append(self._repo_revision_to_key(repo_revision))
+            else:
+                # Only one version, show just the model name
+                choices.append(repo_id)
+        logger.debug("Available choices for parameter '%s': %s", self._parameter_name, choices)
+        return choices
+
+    def validate_before_node_run(self) -> list[Exception] | None:
+        self.refresh_parameters()
+        try:
+            self.get_repo_revision()
+        except Exception as e:
+            return [e]
+
+        return None
+
+    def list_repo_revisions(self) -> list[tuple[str, str]]:
+        return self._repo_revisions
+
+    def get_repo_revision(self) -> tuple[str, str]:
+        value = self._node.get_parameter_value(self._parameter_name)
+        if value is None:
+            msg = "Model download required!"
+            raise RuntimeError(msg)
+
+        # Parse the value using _key_to_repo_revision
+        repo_id, revision = self._key_to_repo_revision(value)
+
+        # If revision is empty (just model name), find it in our stored list
+        if not revision:
+            for stored_repo_id, stored_revision in self._repo_revisions:
+                if stored_repo_id == repo_id:
+                    logger.debug("Using revision '%s' for model '%s'", stored_revision, repo_id)
+                    return stored_repo_id, stored_revision
+            # If not found, raise an error
+            msg = f"Model '{repo_id}' not found in available models!"
+            raise RuntimeError(msg)
+
+        # If revision was provided, return it directly
+        return repo_id, revision
+
+    def get_help_message(self) -> str:
+        download_models = "\n".join([f"  {model}" for model in self.get_download_models()])
+
+        return (
+            "Model download required to continue.\n\n"
+            "To download models:\n\n"
+            "1. Navigate to Settings -> Model Management\n\n"
+            "2. Search for the model(s) you need and click the download button:\n"
+            f"{download_models}\n\n"
+            "After completing these steps, a dropdown menu with available models will appear."
+        )
+
+    @abstractmethod
+    def fetch_repo_revisions(self) -> list[tuple[str, str]]: ...
+
+    @abstractmethod
+    def get_download_commands(self) -> list[str]: ...
+
+    @abstractmethod
+    def get_download_models(self) -> list[str]: ...

griptape_nodes/exe_types/param_components/huggingface/huggingface_repo_file_parameter.py

@@ -0,0 +1,38 @@
+import logging
+
+from griptape_nodes.exe_types.node_types import BaseNode
+from griptape_nodes.exe_types.param_components.huggingface.huggingface_model_parameter import HuggingFaceModelParameter
+from griptape_nodes.exe_types.param_components.huggingface.huggingface_utils import (
+    list_repo_revisions_with_file_in_cache,
+)
+
+logger = logging.getLogger("griptape_nodes")
+
+
+class HuggingFaceRepoFileParameter(HuggingFaceModelParameter):
+    def __init__(self, node: BaseNode, repo_files: list[tuple[str, str]], parameter_name: str = "model"):
+        super().__init__(node, parameter_name)
+        self._repo_files = repo_files
+        self.refresh_parameters()
+
+    def fetch_repo_revisions(self) -> list[tuple[str, str]]:
+        return [
+            repo_revision
+            for (repo, file) in self._repo_files
+            for repo_revision in list_repo_revisions_with_file_in_cache(repo, file)
+        ]
+
+    def get_download_commands(self) -> list[str]:
+        return [f'huggingface-cli download "{repo}" "{file}"' for (repo, file) in self._repo_files]
+
+    def get_download_models(self) -> list[str]:
+        """Returns a list of model names that should be downloaded."""
+        return [repo for (repo, file) in self._repo_files]
+
+    def get_repo_filename(self) -> str:
+        repo_id, _ = self.get_repo_revision()
+        for repo, file in self._repo_files:
+            if repo == repo_id:
+                return file
+        msg = f"File not found for repository {repo_id}"
+        raise ValueError(msg)

griptape_nodes/exe_types/param_components/huggingface/huggingface_repo_parameter.py

@@ -0,0 +1,33 @@
+import logging
+
+from griptape_nodes.exe_types.node_types import BaseNode
+from griptape_nodes.exe_types.param_components.huggingface.huggingface_model_parameter import HuggingFaceModelParameter
+from griptape_nodes.exe_types.param_components.huggingface.huggingface_utils import (
+    list_all_repo_revisions_in_cache,
+    list_repo_revisions_in_cache,
+)
+
+logger = logging.getLogger("griptape_nodes")
+
+
+class HuggingFaceRepoParameter(HuggingFaceModelParameter):
+    def __init__(
+        self, node: BaseNode, repo_ids: list[str], parameter_name: str = "model", *, list_all_models: bool = False
+    ):
+        super().__init__(node, parameter_name)
+        self._repo_ids = repo_ids
+        self._list_all_models = list_all_models
+        self.refresh_parameters()
+
+    def fetch_repo_revisions(self) -> list[tuple[str, str]]:
+        if self._list_all_models:
+            all_revisions = list_all_repo_revisions_in_cache()
+            return sorted(all_revisions, key=lambda x: x[0] not in self._repo_ids)
+        return [repo_revision for repo in self._repo_ids for repo_revision in list_repo_revisions_in_cache(repo)]
+
+    def get_download_commands(self) -> list[str]:
+        return [f'huggingface-cli download "{repo}"' for repo in self._repo_ids]
+
+    def get_download_models(self) -> list[str]:
+        """Returns a list of model names that should be downloaded."""
+        return self._repo_ids