griptape-nodes 0.52.1__py3-none-any.whl → 0.54.0__py3-none-any.whl

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/traits/traits.json

@@ -1,4 +1,8 @@
 {
     "class_name": "MinMax",
     "file_name": "minmax.py"
+},
+{
+    "class_name": "ColorPicker",
+    "file_name": "color_picker.py"
 }

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.52.1.dist-info → griptape_nodes-0.54.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: griptape-nodes
-Version: 0.52.1
+Version: 0.54.0
 Summary: Add your description here
 Requires-Dist: griptape>=1.8.2
 Requires-Dist: pydantic>=2.10.6
@@ -19,6 +19,9 @@ Requires-Dist: mcp[ws]>=1.10.1
 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