griptape-nodes 0.53.0__py3-none-any.whl → 0.54.1__py3-none-any.whl

griptape_nodes/traits/button.py

@@ -1,6 +1,6 @@
 import logging
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING, Literal, get_args
 
 from griptape_nodes.exe_types.core_types import NodeMessagePayload, NodeMessageResult, Trait
 
@@ -63,15 +63,22 @@ class OnClickMessageResultPayload(NodeMessagePayload):
     button_details: ButtonDetailsMessagePayload
 
 
+class SetButtonStatusMessagePayload(NodeMessagePayload):
+    """Payload for setting button status with explicit field updates."""
+
+    updates: dict[str, str | bool | None]
+
+
 @dataclass(eq=False)
 class Button(Trait):
     # Specific callback types for better type safety and clarity
-    type OnClickCallback = Callable[[Button, ButtonDetailsMessagePayload], NodeMessageResult]
-    type GetButtonStateCallback = Callable[[Button, ButtonDetailsMessagePayload], NodeMessageResult]
+    type OnClickCallback = Callable[[Button, ButtonDetailsMessagePayload], NodeMessageResult | None]
+    type GetButtonStateCallback = Callable[[Button, ButtonDetailsMessagePayload], NodeMessageResult | None]
 
     # Static message type constants
     ON_CLICK_MESSAGE_TYPE = "on_click"
     GET_BUTTON_STATUS_MESSAGE_TYPE = "get_button_status"
+    SET_BUTTON_STATUS_MESSAGE_TYPE = "set_button_status"
 
     # Button styling and behavior properties
     label: str = "Button"
@@ -169,7 +176,7 @@ class Button(Trait):
 
         return options
 
-    def on_message_received(self, message_type: str, message: NodeMessagePayload | None) -> NodeMessageResult | None:
+    def on_message_received(self, message_type: str, message: NodeMessagePayload | None) -> NodeMessageResult | None:  # noqa: PLR0911
         """Handle messages sent to this button trait.
 
         Args:
@@ -185,7 +192,16 @@ class Button(Trait):
                     try:
                         # Pre-fill button details with current state and pass to callback
                         button_details = self.get_button_details()
-                        return self.on_click_callback(self, button_details)
+                        result = self.on_click_callback(self, button_details)
+
+                        # If callback returns None, provide optimistic success result
+                        if result is None:
+                            result = NodeMessageResult(
+                                success=True,
+                                details=f"Button '{self.label}' clicked successfully",
+                                response=button_details,
+                            )
+                        return result  # noqa: TRY300
                     except Exception as e:
                         return NodeMessageResult(
                             success=False,
@@ -202,7 +218,17 @@ class Button(Trait):
                     try:
                         # Pre-fill button details with current state and pass to callback
                         button_details = self.get_button_details()
-                        return self.get_button_state_callback(self, button_details)
+                        result = self.get_button_state_callback(self, button_details)
+
+                        # If callback returns None, provide optimistic success result
+                        if result is None:
+                            result = NodeMessageResult(
+                                success=True,
+                                details=f"Button '{self.label}' state retrieved successfully",
+                                response=button_details,
+                                altered_workflow_state=False,
+                            )
+                        return result  # noqa: TRY300
                     except Exception as e:
                         return NodeMessageResult(
                             success=False,
@@ -212,6 +238,9 @@ class Button(Trait):
                 else:
                     return self._default_get_button_status(message_type, message)
 
+            case self.SET_BUTTON_STATUS_MESSAGE_TYPE:
+                return self._handle_set_button_status(message)
+
         # Delegate to parent implementation for unhandled messages or no callback
         return super().on_message_received(message_type, message)
 
@@ -229,3 +258,92 @@ class Button(Trait):
             response=button_details,
             altered_workflow_state=False,
         )
+
+    def _handle_set_button_status(self, message: NodeMessagePayload | None) -> NodeMessageResult:  # noqa: C901
+        """Handle set button status messages by updating fields specified in the updates dict."""
+        if not message:
+            return NodeMessageResult(
+                success=False,
+                details="No message payload provided for set_button_status",
+                response=None,
+                altered_workflow_state=False,
+            )
+
+        if not isinstance(message, SetButtonStatusMessagePayload):
+            return NodeMessageResult(
+                success=False,
+                details="Invalid message payload type for set_button_status",
+                response=None,
+                altered_workflow_state=False,
+            )
+
+        # Track which fields were updated
+        updated_fields = []
+        validation_errors = []
+
+        # Valid field names and their expected types
+        valid_fields = {
+            "label": str,
+            "variant": str,  # Will validate against ButtonVariant literals
+            "size": str,  # Will validate against ButtonSize literals
+            "state": str,  # Will validate against ButtonState literals
+            "icon": str,
+            "icon_class": str,
+            "icon_position": str,  # Will validate against IconPosition literals
+            "full_width": bool,
+            "loading_label": str,
+            "loading_icon": str,
+            "loading_icon_class": str,
+        }
+
+        # Process each update
+        for field_name, value in message.updates.items():
+            # Check if field is valid
+            if field_name not in valid_fields:
+                validation_errors.append(f"Invalid field: {field_name}")
+                continue
+
+            # Type check if value is not None
+            if value is not None and not isinstance(value, valid_fields[field_name]):
+                validation_errors.append(
+                    f"Invalid type for {field_name}: expected {valid_fields[field_name].__name__}, got {type(value).__name__}"
+                )
+                continue
+
+            # Additional validation for Literal types
+            if field_name == "variant" and value is not None and value not in get_args(ButtonVariant):
+                validation_errors.append(f"Invalid variant: {value}")
+                continue
+            if field_name == "size" and value is not None and value not in get_args(ButtonSize):
+                validation_errors.append(f"Invalid size: {value}")
+                continue
+            if field_name == "state" and value is not None and value not in get_args(ButtonState):
+                validation_errors.append(f"Invalid state: {value}")
+                continue
+            if field_name == "icon_position" and value is not None and value not in get_args(IconPosition):
+                validation_errors.append(f"Invalid icon_position: {value}")
+                continue
+
+            # Update the field
+            setattr(self, field_name, value)
+            updated_fields.append(field_name)
+
+        # Return validation errors if any
+        if validation_errors:
+            return NodeMessageResult(
+                success=False,
+                details=f"Validation errors: {'; '.join(validation_errors)}",
+                response=None,
+                altered_workflow_state=False,
+            )
+
+        # Return success with updated button details
+        button_details = self.get_button_details()
+        fields_str = ", ".join(updated_fields) if updated_fields else "no fields"
+
+        return NodeMessageResult(
+            success=True,
+            details=f"Button '{self.label}' updated ({fields_str})",
+            response=button_details,
+            altered_workflow_state=True,
+        )

griptape_nodes/traits/multi_options.py

@@ -0,0 +1,188 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from griptape_nodes.exe_types.core_types import Parameter, Trait
+
+
+@dataclass(eq=False)
+class MultiOptions(Trait):
+    # SERIALIZATION BUG FIX EXPLANATION:
+    #
+    # PROBLEM: Similar to Options trait, MultiOptions had a potential serialization bug
+    # where dynamically populated multi-options lists would work correctly during runtime
+    # but could revert after save/reload cycles. This happens because:
+    # 1. trait.choices was the "source of truth" during runtime
+    # 2. ui_options["multi_options"] was populated from trait.choices
+    # 3. Only ui_options gets serialized/deserialized (not trait fields)
+    # 4. After reload, trait.choices was stale but ui_options had correct data
+    # 5. Converters used stale trait.choices, causing validation issues
+    #
+    # SOLUTION: Make ui_options the primary source of truth, with _choices as fallback
+    # 1. choices property reads from ui_options["multi_options"] when available
+    # 2. choices setter writes to BOTH _choices and ui_options (dual sync)
+    # 3. This ensures serialized ui_options data is used after deserialization
+    # 4. _choices provides safety fallback if ui_options is missing/corrupted
+
+    _choices: list = field(default_factory=lambda: ["choice 1", "choice 2", "choice 3"])
+    element_id: str = field(default_factory=lambda: "MultiOptions")
+    placeholder: str = field(default="Select options...")
+    max_selected_display: int = field(default=3)
+    show_search: bool = field(default=True)
+    icon_size: str = field(default="small")
+
+    def __init__(
+        self,
+        *,
+        choices: list | None = None,
+        placeholder: str = "Select options...",
+        max_selected_display: int = 3,
+        show_search: bool = True,
+        icon_size: str = "small",
+    ) -> None:
+        super().__init__()
+        # Set choices through property to ensure dual sync from the start
+        if choices is not None:
+            self.choices = choices
+
+        self.placeholder = placeholder
+        self.max_selected_display = max_selected_display
+        self.show_search = show_search
+
+        # Validate icon_size
+        if icon_size not in ["small", "large"]:
+            self.icon_size = "small"
+        else:
+            self.icon_size = icon_size
+
+    @property
+    def choices(self) -> list:
+        """Get multi-options choices with ui_options as primary source of truth.
+
+        CRITICAL: This property prioritizes ui_options["multi_options"]["choices"] over _choices
+        because ui_options gets properly serialized/deserialized while trait fields don't.
+
+        Read priority:
+        1. FIRST: ui_options["multi_options"]["choices"] (survives serialization cycles)
+        2. FALLBACK: _choices field (safety net for edge cases)
+
+        This prevents bugs where available choices could become stale after reload.
+        """
+        # Check if we have a parent parameter with ui_options (normal case after trait attachment)
+        if self._parent and hasattr(self._parent, "ui_options"):
+            ui_options = getattr(self._parent, "ui_options", None)
+            if (
+                isinstance(ui_options, dict)
+                and "multi_options" in ui_options
+                and isinstance(ui_options["multi_options"], dict)
+                and "choices" in ui_options["multi_options"]
+            ):
+                # Use live ui_options data (this survives serialization)
+                return ui_options["multi_options"]["choices"]
+
+        # Fallback to internal field (used during initialization or if ui_options missing)
+        return self._choices
+
+    @choices.setter
+    def choices(self, value: list) -> None:
+        """Set multi-options choices with dual synchronization.
+
+        CRITICAL: This setter writes to BOTH locations to maintain consistency:
+        1. _choices field (for fallback and ui_options_for_trait())
+        2. ui_options["multi_options"]["choices"] (for serialization and runtime use)
+
+        This dual sync ensures:
+        - Immediate runtime consistency
+        - Proper serialization of choices data
+        - Fallback safety if either location fails
+        """
+        # Always update internal field first (provides fallback safety)
+        self._choices = value
+
+        # Sync to ui_options if we have a parent parameter (normal case after trait attachment)
+        if self._parent and hasattr(self._parent, "ui_options"):
+            ui_options = getattr(self._parent, "ui_options", None)
+            if not isinstance(ui_options, dict):
+                # Initialize ui_options if it doesn't exist or isn't a dict
+                self._parent.ui_options = {}  # type: ignore[attr-defined]
+
+            # Ensure multi_options exists and is a dict
+            if "multi_options" not in self._parent.ui_options or not isinstance(  # type: ignore[attr-defined]
+                self._parent.ui_options["multi_options"],  # type: ignore[attr-defined]
+                dict,
+            ):
+                self._parent.ui_options["multi_options"] = {}  # type: ignore[attr-defined]
+
+            # Write choices to ui_options (this gets serialized and survives reload)
+            self._parent.ui_options["multi_options"]["choices"] = value  # type: ignore[attr-defined]
+
+    @classmethod
+    def get_trait_keys(cls) -> list[str]:
+        return ["multi_options"]
+
+    def converters_for_trait(self) -> list[Callable]:
+        def converter(value: Any) -> Any:
+            # CRITICAL: This converter uses self.choices property (not _choices field)
+            # The property reads from ui_options first, ensuring we use post-deserialization
+            # choices data instead of stale trait field data.
+
+            # Handle case where value is not a list (convert single values to list)
+            if not isinstance(value, list):
+                if value is None:
+                    return []
+                value = [value]
+
+            # Filter out invalid choices and return valid ones
+            valid_choices = [v for v in value if v in self.choices]
+
+            # If no valid choices, return empty list (allow empty selection)
+            return valid_choices
+
+        return [converter]
+
+    def validators_for_trait(self) -> list[Callable[[Parameter, Any], Any]]:
+        def validator(param: Parameter, value: Any) -> None:  # noqa: ARG001
+            # CRITICAL: This validator uses self.choices property (not _choices field)
+            # Same reasoning as converter - use live ui_options data after deserialization
+
+            # Allow None or empty list as valid (no selection)
+            if value is None or value == []:
+                return
+
+            # Ensure value is a list
+            if not isinstance(value, list):
+                msg = "MultiOptions value must be a list"
+                raise TypeError(msg)
+
+            # Check that all selected values are valid choices
+            invalid_choices = [v for v in value if v not in self.choices]
+            if invalid_choices:
+                msg = f"Invalid choices: {invalid_choices}"
+                raise ValueError(msg)
+
+        return [validator]
+
+    def ui_options_for_trait(self) -> dict:
+        """Provide UI options for trait initialization.
+
+        IMPORTANT: This method uses _choices (not self.choices property) to avoid
+        circular dependency during Parameter.ui_options property construction:
+
+        Circular dependency would be:
+        1. Parameter.ui_options calls trait.ui_options_for_trait()
+        2. ui_options_for_trait() calls self.choices property
+        3. choices property tries to read parent.ui_options
+        4. This triggers Parameter.ui_options again → infinite recursion
+
+        Using _choices directly breaks this cycle while still providing the correct
+        initial choices for UI rendering. The property-based sync handles runtime updates.
+        """
+        return {
+            "multi_options": {
+                "choices": self._choices,
+                "placeholder": self.placeholder,
+                "max_selected_display": self.max_selected_display,
+                "show_search": self.show_search,
+                "icon_size": self.icon_size,
+            }
+        }

griptape_nodes/traits/numbers_selector.py

@@ -0,0 +1,77 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from griptape_nodes.exe_types.core_types import Parameter, ParameterMode, Trait
+
+
+@dataclass(eq=False)
+class NumbersSelector(Trait):
+    defaults: dict[str, float] = field(kw_only=True)
+    step: float = 1.0
+    overall_min: float | None = None
+    overall_max: float | None = None
+    element_id: str = field(default_factory=lambda: "NumbersSelector")
+
+    _allowed_modes: set = field(default_factory=lambda: {ParameterMode.PROPERTY})
+
+    def __init__(
+        self,
+        defaults: dict[str, float],
+        step: float = 1.0,
+        overall_min: float | None = None,
+        overall_max: float | None = None,
+    ) -> None:
+        super().__init__()
+        self.defaults = defaults
+        self.step = step
+        self.overall_min = overall_min
+        self.overall_max = overall_max
+
+    @classmethod
+    def get_trait_keys(cls) -> list[str]:
+        return ["numbers_selector"]
+
+    def ui_options_for_trait(self) -> dict:
+        return {
+            "numbers_selector": {
+                "step": self.step,
+                "overall_min": self.overall_min,
+                "overall_max": self.overall_max,
+                "defaults": self.defaults,
+            }
+        }
+
+    def display_options_for_trait(self) -> dict:
+        return {}
+
+    def converters_for_trait(self) -> list[Callable]:
+        return []
+
+    def validators_for_trait(self) -> list[Callable[..., Any]]:
+        def validate(_param: Parameter, value: Any) -> None:
+            if value is None:
+                return
+
+            if not isinstance(value, dict):
+                msg = "NumbersSelector value must be a dictionary"
+                raise TypeError(msg)
+
+            for key, val in value.items():
+                if not isinstance(key, str):
+                    msg = f"NumbersSelector keys must be strings, got {type(key)}"
+                    raise TypeError(msg)
+
+                if not isinstance(val, (int, float)):
+                    msg = f"NumbersSelector values must be numbers, got {type(val)} for key '{key}'"
+                    raise TypeError(msg)
+
+                if self.overall_min is not None and val < self.overall_min:
+                    msg = f"Value {val} for key '{key}' is below minimum {self.overall_min}"
+                    raise ValueError(msg)
+
+                if self.overall_max is not None and val > self.overall_max:
+                    msg = f"Value {val} for key '{key}' is above maximum {self.overall_max}"
+                    raise ValueError(msg)
+
+        return [validate]

griptape_nodes/traits/options.py

@@ -7,15 +7,90 @@ from griptape_nodes.exe_types.core_types import Parameter, Trait
 
 @dataclass(eq=False)
 class Options(Trait):
-    choices: list[str] = field(default_factory=lambda: ["choice 1", "choice 2", "choice 3"])
+    # SERIALIZATION BUG FIX EXPLANATION:
+    #
+    # PROBLEM: Options trait had a serialization bug where dynamically populated dropdown
+    # lists would work correctly during runtime but revert to the first choice after
+    # save/reload cycles. This happened because:
+    # 1. trait.choices was the "source of truth" during runtime
+    # 2. ui_options["simple_dropdown"] was populated from trait.choices
+    # 3. Only ui_options gets serialized/deserialized (not trait fields)
+    # 4. After reload, trait.choices was stale but ui_options had correct data
+    # 5. Converters used stale trait.choices, causing values to revert to first choice
+    #
+    # SOLUTION: Make ui_options the primary source of truth, with _choices as fallback
+    # 1. choices property reads from ui_options["simple_dropdown"] when available
+    # 2. choices setter writes to BOTH _choices and ui_options (dual sync)
+    # 3. This ensures serialized ui_options data is used after deserialization
+    # 4. _choices provides safety fallback if ui_options is missing/corrupted
+
+    _choices: list = field(default_factory=lambda: ["choice 1", "choice 2", "choice 3"])
     element_id: str = field(default_factory=lambda: "Options")
 
+    def __init__(self, *, choices: list | None = None) -> None:
+        super().__init__()
+        # Set choices through property to ensure dual sync from the start
+        if choices is not None:
+            self.choices = choices
+
+    @property
+    def choices(self) -> list:
+        """Get dropdown choices with ui_options as primary source of truth.
+
+        CRITICAL: This property prioritizes ui_options["simple_dropdown"] over _choices
+        because ui_options gets properly serialized/deserialized while trait fields don't.
+
+        Read priority:
+        1. FIRST: ui_options["simple_dropdown"] (survives serialization cycles)
+        2. FALLBACK: _choices field (safety net for edge cases)
+
+        This fixes the bug where selected values reverted to first choice after reload.
+        """
+        # Check if we have a parent parameter with ui_options (normal case after trait attachment)
+        if self._parent and hasattr(self._parent, "ui_options"):
+            ui_options = getattr(self._parent, "ui_options", None)
+            if isinstance(ui_options, dict) and "simple_dropdown" in ui_options:
+                # Use live ui_options data (this survives serialization)
+                return ui_options["simple_dropdown"]
+
+        # Fallback to internal field (used during initialization or if ui_options missing)
+        return self._choices
+
+    @choices.setter
+    def choices(self, value: list) -> None:
+        """Set dropdown choices with dual synchronization.
+
+        CRITICAL: This setter writes to BOTH locations to maintain consistency:
+        1. _choices field (for fallback and ui_options_for_trait())
+        2. ui_options["simple_dropdown"] (for serialization and runtime use)
+
+        This dual sync ensures:
+        - Immediate runtime consistency
+        - Proper serialization of choices data
+        - Fallback safety if either location fails
+        """
+        # Always update internal field first (provides fallback safety)
+        self._choices = value
+
+        # Sync to ui_options if we have a parent parameter (normal case after trait attachment)
+        if self._parent and hasattr(self._parent, "ui_options"):
+            ui_options = getattr(self._parent, "ui_options", None)
+            if not isinstance(ui_options, dict):
+                # Initialize ui_options if it doesn't exist or isn't a dict
+                self._parent.ui_options = {}  # type: ignore[attr-defined]
+            # Write choices to ui_options (this gets serialized and survives reload)
+            self._parent.ui_options["simple_dropdown"] = value  # type: ignore[attr-defined]
+
     @classmethod
     def get_trait_keys(cls) -> list[str]:
         return ["options", "models"]
 
     def converters_for_trait(self) -> list[Callable]:
         def converter(value: Any) -> Any:
+            # CRITICAL: This converter uses self.choices property (not _choices field)
+            # The property reads from ui_options first, ensuring we use post-deserialization
+            # choices data instead of stale trait field data. This prevents the bug where
+            # selected values revert to first choice after save/reload.
             if value not in self.choices:
                 return self.choices[0]
             return value
@@ -24,6 +99,8 @@ class Options(Trait):
 
     def validators_for_trait(self) -> list[Callable[[Parameter, Any], Any]]:
         def validator(param: Parameter, value: Any) -> None:  # noqa: ARG001
+            # CRITICAL: This validator uses self.choices property (not _choices field)
+            # Same reasoning as converter - use live ui_options data after deserialization
             if value not in self.choices:
                 msg = "Choice not allowed"
                 raise ValueError(msg)
@@ -31,4 +108,18 @@ class Options(Trait):
         return [validator]
 
     def ui_options_for_trait(self) -> dict:
-        return {"simple_dropdown": self.choices}
+        """Provide UI options for trait initialization.
+
+        IMPORTANT: This method uses _choices (not self.choices property) to avoid
+        circular dependency during Parameter.ui_options property construction:
+
+        Circular dependency would be:
+        1. Parameter.ui_options calls trait.ui_options_for_trait()
+        2. ui_options_for_trait() calls self.choices property
+        3. choices property tries to read parent.ui_options
+        4. This triggers Parameter.ui_options again → infinite recursion
+
+        Using _choices directly breaks this cycle while still providing the correct
+        initial choices for UI rendering. The property-based sync handles runtime updates.
+        """
+        return {"simple_dropdown": self._choices}

griptape_nodes/utils/async_utils.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import inspect
+import logging
 import subprocess
 from typing import TYPE_CHECKING, Any
 
@@ -11,6 +12,9 @@ if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
 
 
+logger = logging.getLogger(__name__)
+
+
 async def call_function(func: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
     """Call a function, handling both sync and async cases.
 
@@ -87,3 +91,30 @@ async def subprocess_run(
         )
 
     return completed_process
+
+
+async def cancel_subprocess(process: asyncio.subprocess.Process, name: str = "process") -> None:
+    """Cancel a subprocess with graceful termination then force kill.
+
+    Args:
+        process: The subprocess to cancel
+        name: Name/description for logging purposes
+    """
+    if process.returncode is not None:  # Process already terminated
+        return
+
+    try:
+        process.terminate()
+        logger.info("Terminated %s", name)
+
+        # Give process a chance to terminate gracefully
+        try:
+            await asyncio.wait_for(process.wait(), timeout=5.0)
+        except TimeoutError:
+            # Force kill if it doesn't terminate
+            process.kill()
+            logger.info("Force killed %s", name)
+            await process.wait()
+    except ProcessLookupError:
+        # Process already terminated
+        pass

{griptape_nodes-0.53.0.dist-info → griptape_nodes-0.54.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: griptape-nodes
-Version: 0.53.0
+Version: 0.54.1
 Summary: Add your description here
 Requires-Dist: griptape>=1.8.2
 Requires-Dist: pydantic>=2.10.6
@@ -20,6 +20,8 @@ Requires-Dist: binaryornot>=0.4.4
 Requires-Dist: pillow>=11.3.0
 Requires-Dist: watchfiles>=1.1.0
 Requires-Dist: typer>=0.15.0
+Requires-Dist: huggingface-hub>=0.28.0
+Requires-Dist: rich>=14.1.0
 Requires-Dist: austin-dist>=3.7.0 ; extra == 'profiling'
 Requires-Python: >=3.12.0, <3.13
 Provides-Extra: profiling