griptape-nodes 0.43.1__py3-none-any.whl → 0.45.0__py3-none-any.whl

griptape_nodes/drivers/storage/griptape_cloud_storage_driver.py

@@ -135,6 +135,37 @@ class GriptapeCloudStorageDriver(BaseStorageDriver):
         logger.info("Created new Griptape Cloud bucket '%s' with ID: %s", bucket_name, bucket_id)
         return bucket_id
 
+    def list_files(self) -> list[str]:
+        """List all files in storage.
+
+        Returns:
+            A list of file names in storage.
+
+        Raises:
+            RuntimeError: If file listing fails.
+        """
+        url = urljoin(self.base_url, f"/api/buckets/{self.bucket_id}/assets")
+        try:
+            response = httpx.get(url, headers=self.headers, params={"prefix": self.static_files_directory or ""})
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            msg = f"Failed to list files in bucket {self.bucket_id}: {e}"
+            logger.error(msg)
+            raise RuntimeError(msg) from e
+
+        response_data = response.json()
+        assets = response_data.get("assets", [])
+
+        file_names = []
+        for asset in assets:
+            name = asset.get("name", "")
+            # Remove the static files directory prefix if it exists
+            if self.static_files_directory and name.startswith(f"{self.static_files_directory}/"):
+                name = name[len(f"{self.static_files_directory}/") :]
+            file_names.append(name)
+
+        return file_names
+
     @staticmethod
     def list_buckets(*, base_url: str, api_key: str) -> list[dict]:
         """List all buckets in Griptape Cloud.
@@ -158,3 +189,20 @@ class GriptapeCloudStorageDriver(BaseStorageDriver):
             raise RuntimeError(msg) from e
 
         return response.json().get("buckets", [])
+
+    def delete_file(self, file_name: str) -> None:
+        """Delete a file from the bucket.
+
+        Args:
+            file_name: The name of the file to delete.
+        """
+        full_file_path = self._get_full_file_path(file_name)
+        url = urljoin(self.base_url, f"/api/buckets/{self.bucket_id}/assets/{full_file_path}")
+
+        try:
+            response = httpx.delete(url, headers=self.headers)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            msg = f"Failed to delete file {file_name}: {e}"
+            logger.error(msg)
+            raise RuntimeError(msg) from e

griptape_nodes/drivers/storage/local_storage_driver.py

@@ -53,3 +53,40 @@ class LocalStorageDriver(BaseStorageDriver):
         # Add a cache-busting query parameter to the URL so that the browser always reloads the file
         cache_busted_url = f"{url}?t={int(time.time())}"
         return cache_busted_url
+
+    def delete_file(self, file_name: str) -> None:
+        """Delete a file from local storage.
+
+        Args:
+            file_name: The name of the file to delete.
+        """
+        # Use the static server's delete endpoint
+        delete_url = urljoin(self.base_url, f"/static-files/{file_name}")
+
+        try:
+            response = httpx.delete(delete_url)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            msg = f"Failed to delete file {file_name}: {e}"
+            logger.error(msg)
+            raise RuntimeError(msg) from e
+
+    def list_files(self) -> list[str]:
+        """List all files in local storage.
+
+        Returns:
+            A list of file names in storage.
+        """
+        # Use the static server's list endpoint
+        list_url = urljoin(self.base_url, "/static-uploads/")
+
+        try:
+            response = httpx.get(list_url)
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            msg = f"Failed to list files: {e}"
+            logger.error(msg)
+            raise RuntimeError(msg) from e
+
+        response_data = response.json()
+        return response_data.get("files", [])

griptape_nodes/exe_types/core_types.py

@@ -244,6 +244,11 @@ class BaseNodeElement:
             "name": self.name,
             "node_name": self._node_context.name,
         }
+        # If ui_options changed, send the complete ui_options from to_dict()
+        complete_dict = self.to_dict()
+        if "ui_options" in complete_dict:
+            self._changes["ui_options"] = complete_dict["ui_options"]
+
         event_data.update(self._changes)
 
         # Publish the event
@@ -295,11 +300,28 @@ class BaseNodeElement:
             self._node_context._emit_parameter_lifecycle_event(child)
 
     def remove_child(self, child: BaseNodeElement | str) -> None:
+        """Remove a child element from the hierarchy.
+
+        This method recursively searches through the element hierarchy to find and remove
+        the specified child. When the child is found in a descendant container (e.g., a
+        ParameterList), it delegates to that container's remove_child() method to ensure
+        proper cleanup and event handling (like marking parent nodes as unresolved).
+
+        Args:
+            child: The child element to remove, either as an object or by name string
+        """
         ui_elements: list[BaseNodeElement] = [self]
         for ui_element in ui_elements:
             if child in ui_element._children:
-                child._parent = None
-                ui_element._children.remove(child)
+                # Delegate to the actual parent container's remove_child method.
+                # This ensures specialized containers (like ParameterList) can perform
+                # their specific cleanup logic (e.g., marking parent nodes as unresolved).
+                if ui_element is not self:
+                    ui_element.remove_child(child)
+                else:
+                    # We are the direct parent, so handle removal directly
+                    child._parent = None
+                    ui_element._children.remove(child)
                 break
             ui_elements.extend(ui_element._children)
         if self._node_context is not None and isinstance(child, BaseNodeElement):
@@ -366,8 +388,23 @@ class BaseNodeElement:
         return event_data
 
 
-@dataclass(kw_only=True)
-class ParameterMessage(BaseNodeElement):
+class UIOptionsMixin:
+    """Mixin providing UI options update functionality for classes with ui_options."""
+
+    def update_ui_options_key(self, key: str, value: Any) -> None:
+        """Update a single UI option key."""
+        ui_options = self.ui_options
+        ui_options[key] = value
+        self.ui_options = ui_options
+
+    def update_ui_options(self, updates: dict[str, Any]) -> None:
+        """Update multiple UI options at once."""
+        ui_options = self.ui_options
+        ui_options.update(updates)
+        self.ui_options = ui_options
+
+
+class ParameterMessage(BaseNodeElement, UIOptionsMixin):
     """Represents a UI message element, such as a warning or informational text."""
 
     # Define default titles as a class-level constant
@@ -384,13 +421,97 @@ class ParameterMessage(BaseNodeElement):
     type VariantType = Literal["info", "warning", "error", "success", "tip", "none"]
 
     element_type: str = field(default_factory=lambda: ParameterMessage.__name__)
-    variant: VariantType
-    title: str | None = None
-    value: str
-    button_link: str | None = None
-    button_text: str | None = None
-    full_width: bool = False
-    ui_options: dict = field(default_factory=dict)
+    _variant: VariantType = field(init=False)
+    _title: str | None = field(default=None, init=False)
+    _value: str = field(init=False)
+    _button_link: str | None = field(default=None, init=False)
+    _button_text: str | None = field(default=None, init=False)
+    _full_width: bool = field(default=False, init=False)
+    _ui_options: dict = field(default_factory=dict, init=False)
+
+    def __init__(  # noqa: PLR0913
+        self,
+        variant: VariantType,
+        value: str,
+        *,
+        title: str | None = None,
+        button_link: str | None = None,
+        button_text: str | None = None,
+        full_width: bool = False,
+        ui_options: dict | None = None,
+        **kwargs,
+    ):
+        super().__init__(element_type=ParameterMessage.__name__, **kwargs)
+        self._variant = variant
+        self._title = title
+        self._value = value
+        self._button_link = button_link
+        self._button_text = button_text
+        self._full_width = full_width
+        self._ui_options = ui_options or {}
+
+    @property
+    def variant(self) -> VariantType:
+        return self._variant
+
+    @variant.setter
+    @BaseNodeElement.emits_update_on_write
+    def variant(self, value: VariantType) -> None:
+        self._variant = value
+
+    @property
+    def title(self) -> str | None:
+        return self._title
+
+    @title.setter
+    @BaseNodeElement.emits_update_on_write
+    def title(self, value: str | None) -> None:
+        self._title = value
+
+    @property
+    def value(self) -> str:
+        return self._value
+
+    @value.setter
+    @BaseNodeElement.emits_update_on_write
+    def value(self, value: str) -> None:
+        self._value = value
+
+    @property
+    def button_link(self) -> str | None:
+        return self._button_link
+
+    @button_link.setter
+    @BaseNodeElement.emits_update_on_write
+    def button_link(self, value: str | None) -> None:
+        self._button_link = value
+
+    @property
+    def button_text(self) -> str | None:
+        return self._button_text
+
+    @button_text.setter
+    @BaseNodeElement.emits_update_on_write
+    def button_text(self, value: str | None) -> None:
+        self._button_text = value
+
+    @property
+    def full_width(self) -> bool:
+        return self._full_width
+
+    @full_width.setter
+    @BaseNodeElement.emits_update_on_write
+    def full_width(self, value: bool) -> None:
+        self._full_width = value
+
+    @property
+    def ui_options(self) -> dict:
+        return self._ui_options
+
+    @ui_options.setter
+    @BaseNodeElement.emits_update_on_write
+    def ui_options(self, value: dict) -> None:
+        self._ui_options = value
 
     def to_dict(self) -> dict[str, Any]:
         data = super().to_dict()
@@ -429,11 +550,21 @@ class ParameterMessage(BaseNodeElement):
         return event_data
 
 
-@dataclass(kw_only=True)
-class ParameterGroup(BaseNodeElement):
+class ParameterGroup(BaseNodeElement, UIOptionsMixin):
     """UI element for a group of parameters."""
 
-    ui_options: dict = field(default_factory=dict)
+    def __init__(self, name: str, ui_options: dict | None = None, **kwargs):
+        super().__init__(name=name, **kwargs)
+        self._ui_options = ui_options or {}
+
+    @property
+    def ui_options(self) -> dict:
+        return self._ui_options
+
+    @ui_options.setter
+    @BaseNodeElement.emits_update_on_write
+    def ui_options(self, value: dict) -> None:
+        self._ui_options = value
 
     def to_dict(self) -> dict[str, Any]:
         """Returns a nested dictionary representation of this node and its children.
@@ -541,7 +672,7 @@ class ParameterBase(BaseNodeElement, ABC):
         pass
 
 
-class Parameter(BaseNodeElement):
+class Parameter(BaseNodeElement, UIOptionsMixin):
     # 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
@@ -552,7 +683,11 @@ class Parameter(BaseNodeElement):
     tooltip_as_input: str | list[dict] | None = None
     tooltip_as_property: str | list[dict] | None = None
     tooltip_as_output: str | list[dict] | None = None
+
+    # "settable" here means whether it can be assigned to during regular business operation.
+    # During save/load, this value IS still serialized to save its proper state.
     settable: bool = True
+
     user_defined: bool = False
     _allowed_modes: set = field(
         default_factory=lambda: {
@@ -594,7 +729,7 @@ class Parameter(BaseNodeElement):
         if not element_id:
             element_id = str(uuid.uuid4().hex)
         if not element_type:
-            element_type = BaseNodeElement.__name__
+            element_type = self.__class__.__name__
         super().__init__(element_id=element_id, element_type=element_type)
         self.name = name
         self.tooltip = tooltip
@@ -748,7 +883,10 @@ class Parameter(BaseNodeElement):
             ui_options = ui_options | trait.ui_options_for_trait()
         ui_options = ui_options | self._ui_options
         if self._parent is not None and isinstance(self._parent, ParameterGroup):
-            ui_options = ui_options | self._parent.ui_options
+            # Access the field value directly for ParameterGroup
+            parent_ui_options = getattr(self._parent, "ui_options", {})
+            if isinstance(parent_ui_options, dict):
+                ui_options = ui_options | parent_ui_options
         return ui_options
 
     @ui_options.setter
@@ -951,6 +1089,7 @@ class ControlParameter(Parameter, ABC):
         traits: set[Trait.__class__ | Trait] | None = None,
         converters: list[Callable[[Any], Any]] | None = None,
         validators: list[Callable[[Parameter, Any], None]] | None = None,
+        ui_options: dict | None = None,
         *,
         user_defined: bool = False,
     ):
@@ -970,6 +1109,7 @@ class ControlParameter(Parameter, ABC):
             traits=traits,
             converters=converters,
             validators=validators,
+            ui_options=ui_options,
             user_defined=user_defined,
             element_type=self.__class__.__name__,
         )
@@ -980,6 +1120,7 @@ class ControlParameterInput(ControlParameter):
         self,
         tooltip: str | list[dict] = "Connection from previous node in the execution chain",
         name: str = "exec_in",
+        display_name: str | None = "Flow In",
         tooltip_as_input: str | list[dict] | None = None,
         tooltip_as_property: str | list[dict] | None = None,
         tooltip_as_output: str | list[dict] | None = None,
@@ -992,6 +1133,11 @@ class ControlParameterInput(ControlParameter):
         allowed_modes = {ParameterMode.INPUT}
         input_types = [ParameterTypeBuiltin.CONTROL_TYPE.value]
 
+        if display_name is None:
+            ui_options = None
+        else:
+            ui_options = {"display_name": display_name}
+
         # Call parent with a few explicit tweaks.
         super().__init__(
             name=name,
@@ -1005,6 +1151,7 @@ class ControlParameterInput(ControlParameter):
             traits=traits,
             converters=converters,
             validators=validators,
+            ui_options=ui_options,
             user_defined=user_defined,
         )
 
@@ -1014,6 +1161,7 @@ class ControlParameterOutput(ControlParameter):
         self,
         tooltip: str | list[dict] = "Connection to the next node in the execution chain",
         name: str = "exec_out",
+        display_name: str | None = "Flow Out",
         tooltip_as_input: str | list[dict] | None = None,
         tooltip_as_property: str | list[dict] | None = None,
         tooltip_as_output: str | list[dict] | None = None,
@@ -1026,6 +1174,11 @@ class ControlParameterOutput(ControlParameter):
         allowed_modes = {ParameterMode.OUTPUT}
         output_type = ParameterTypeBuiltin.CONTROL_TYPE.value
 
+        if display_name is None:
+            ui_options = None
+        else:
+            ui_options = {"display_name": display_name}
+
         # Call parent with a few explicit tweaks.
         super().__init__(
             name=name,
@@ -1039,6 +1192,7 @@ class ControlParameterOutput(ControlParameter):
             traits=traits,
             converters=converters,
             validators=validators,
+            ui_options=ui_options,
             user_defined=user_defined,
         )
 
@@ -1093,6 +1247,23 @@ class ParameterContainer(Parameter, ABC):
             element_type=element_type,
         )
 
+    def __bool__(self) -> bool:
+        """Parameter containers are always truthy, even when empty.
+
+        This overrides Python's default truthiness behavior for containers with __len__().
+        By default, Python makes objects with __len__() falsy when len() == 0, which
+        caused bugs where empty ParameterList/ParameterDictionary objects would fail
+        'if param' checks and fall back to stale cached values instead of computing
+        fresh empty results.
+
+        Unlike standard Python containers, ParameterContainer objects represent
+        parameter structure/definitions rather than just data, so they remain
+        meaningful even when empty.
+
+        See: https://github.com/griptape-ai/griptape-nodes/issues/1799
+        """
+        return True
+
     @abstractmethod
     def add_child_parameter(self) -> Parameter:
         pass
@@ -1224,6 +1395,40 @@ class ParameterList(ParameterContainer):
 
         return param
 
+    def add_child(self, child: BaseNodeElement) -> None:
+        """Override to mark parent node as unresolved when children are added.
+
+        When a ParameterList gains a child parameter, the parent node needs to be
+        marked as unresolved to trigger re-evaluation of the node's state and outputs.
+        """
+        super().add_child(child)
+
+        # Mark the parent node as unresolved since the parameter structure changed
+        if self._node_context is not None:
+            # Import at runtime to avoid circular import
+            from griptape_nodes.exe_types.node_types import NodeResolutionState
+
+            self._node_context.make_node_unresolved(
+                current_states_to_trigger_change_event={NodeResolutionState.RESOLVED, NodeResolutionState.RESOLVING}
+            )
+
+    def remove_child(self, child: BaseNodeElement | str) -> None:
+        """Override to mark parent node as unresolved when children are removed.
+
+        When a ParameterList loses a child parameter, the parent node needs to be
+        marked as unresolved to trigger re-evaluation of the node's state and outputs.
+        """
+        super().remove_child(child)
+
+        # Mark the parent node as unresolved since the parameter structure changed
+        if self._node_context is not None:
+            # Import at runtime to avoid circular import
+            from griptape_nodes.exe_types.node_types import NodeResolutionState
+
+            self._node_context.make_node_unresolved(
+                current_states_to_trigger_change_event={NodeResolutionState.RESOLVED, NodeResolutionState.RESOLVING}
+            )
+
 
 class ParameterKeyValuePair(Parameter):
     def __init__(  # noqa: PLR0913

griptape_nodes/exe_types/node_types.py

@@ -68,6 +68,7 @@ class BaseNode(ABC):
     _entry_control_parameter: Parameter | None = (
         None  # The control input parameter used to enter this node during execution
     )
+    lock: bool = False  # When lock is true, the node is locked and can't be modified. When lock is false, the node is unlocked and can be modified.
 
     @property
     def parameters(self) -> list[Parameter]:
@@ -367,8 +368,10 @@ class BaseNode(ABC):
         """
         parameter = self.get_parameter_by_name(param)
         if parameter is not None:
-            trait = parameter.find_element_by_id("Options")
-            if trait and isinstance(trait, Options):
+            # Find the Options trait by type since element_id is a UUID
+            traits = parameter.find_elements_by_type(Options)
+            if traits:
+                trait = traits[0]  # Take the first Options trait
                 trait.choices = choices
 
                 if default in choices:
@@ -377,6 +380,13 @@ class BaseNode(ABC):
                 else:
                     msg = f"Default model '{default}' is not in the provided choices."
                     raise ValueError(msg)
+
+                # Update the manually set UI options to include the new simple_dropdown
+                if hasattr(parameter, "_ui_options") and parameter._ui_options:
+                    parameter._ui_options["simple_dropdown"] = choices
+            else:
+                msg = f"No Options trait found for parameter '{param}'."
+                raise ValueError(msg)
         else:
             msg = f"Parameter '{param}' not found for updating model choices."
             raise ValueError(msg)
@@ -392,9 +402,14 @@ class BaseNode(ABC):
         """
         parameter = self.get_parameter_by_name(param)
         if parameter is not None:
-            trait = parameter.find_element_by_id("Options")
-            if trait and isinstance(trait, Options):
+            # Find the Options trait by type since element_id is a UUID
+            traits = parameter.find_elements_by_type(Options)
+            if traits:
+                trait = traits[0]  # Take the first Options trait
                 parameter.remove_trait(trait)
+            else:
+                msg = f"No Options trait found for parameter '{param}'."
+                raise ValueError(msg)
         else:
             msg = f"Parameter '{param}' not found for removing options trait."
             raise ValueError(msg)
@@ -575,7 +590,7 @@ class BaseNode(ABC):
         param = self.get_parameter_by_name(param_name)
         if param and isinstance(param, ParameterContainer):
             value = handle_container_parameter(self, param)
-            if value:
+            if value is not None:
                 return value
         if param_name in self.parameter_values:
             return self.parameter_values[param_name]

griptape_nodes/machines/control_flow.py

@@ -88,11 +88,12 @@ class ResolveNodeState(State):
             return CompleteState
 
         # Mark the node unresolved, and broadcast an event to the GUI.
-        context.current_node.make_node_unresolved(
-            current_states_to_trigger_change_event=set(
-                {NodeResolutionState.UNRESOLVED, NodeResolutionState.RESOLVED, NodeResolutionState.RESOLVING}
+        if not context.current_node.lock:
+            context.current_node.make_node_unresolved(
+                current_states_to_trigger_change_event=set(
+                    {NodeResolutionState.UNRESOLVED, NodeResolutionState.RESOLVED, NodeResolutionState.RESOLVING}
+                )
             )
-        )
         # Now broadcast that we have a current control node.
         EventBus.publish_event(
             ExecutionGriptapeNodeEvent(