griptape-nodes 0.69.0__tar.gz → 0.70.1__tar.gz

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: griptape-nodes
-Version: 0.69.0
+Version: 0.70.1
 Summary: Add your description here
 Requires-Dist: griptape>=1.9.0
 Requires-Dist: pydantic>=2.10.6

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "griptape-nodes"
-version = "0.69.0"
+version = "0.70.1"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12.0, <3.13"

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/api_client/client.py

@@ -168,7 +168,11 @@ class Client:
             logger.debug("WebSocket client connected")
         except TimeoutError as e:
             logger.error("Failed to connect WebSocket client: timeout")
-            msg = "Connection timeout"
+            msg = (
+                "Connection timeout - failed to connect to Nodes API. "
+                "This usually indicates an invalid or missing GT_CLOUD_API_KEY. "
+                "Please verify your API key is correct."
+            )
             raise ConnectionError(msg) from e
 
     async def _disconnect(self) -> None:

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/app/app.py

@@ -3,11 +3,14 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import sys
 import threading
 from dataclasses import dataclass
 
+from rich.align import Align
 from rich.console import Console
 from rich.logging import RichHandler
+from rich.panel import Panel
 
 from griptape_nodes.api_client import Client
 from griptape_nodes.retained_mode.events import app_events, execution_events
@@ -113,6 +116,35 @@ logging.basicConfig(
 console = Console()
 
 
+def _ensure_api_key() -> str:
+    """Verify that GT_CLOUD_API_KEY is set, exit with clear error message if not.
+
+    Returns:
+        The API key value
+
+    Raises:
+        SystemExit: If API key is missing or empty
+    """
+    secrets_manager = griptape_nodes.SecretsManager()
+    api_key = secrets_manager.get_secret("GT_CLOUD_API_KEY", should_error_on_not_found=False)
+
+    if not api_key:
+        message = Panel(
+            Align.center(
+                "[bold red]Nodes API key is not set, please run [code]gtn init[/code] with a valid key:[/bold red]\n"
+                "[code]gtn init --api-key <your key>[/code]\n\n"
+                "[bold red]You can generate a new key from [/bold red][bold blue][link=https://nodes.griptape.ai]https://nodes.griptape.ai[/link][/bold blue]",
+            ),
+            title="[red]X[/red] Missing Nodes API Key",
+            border_style="red",
+            padding=(1, 4),
+        )
+        console.print(message)
+        sys.exit(1)
+
+    return api_key
+
+
 def start_app() -> None:
     """Legacy sync entry point - runs async app."""
     try:
@@ -125,6 +157,9 @@ def start_app() -> None:
 
 async def astart_app() -> None:
     """New async app entry point."""
+    # Verify API key is set before starting
+    _ensure_api_key()
+
     # Initialize event queue in main thread
     griptape_nodes.EventManager().initialize_queue()
 
@@ -154,6 +189,22 @@ def _start_websocket_connection() -> None:
 
         # Run the async WebSocket tasks
         loop.run_until_complete(_run_websocket_tasks())
+    except ConnectionError:
+        # Connection failed - likely due to invalid/missing API key
+        message = Panel(
+            Align.center(
+                "[bold red]Failed to connect to Nodes API.[/bold red]\n\n"
+                "This usually indicates an invalid or missing [code]GT_CLOUD_API_KEY[/code].\n\n"
+                "[bold red]Please verify your API key:[/bold red]\n"
+                "[code]gtn init --api-key <your key>[/code]\n\n"
+                "[bold red]You can generate a new key from [/bold red][bold blue][link=https://nodes.griptape.ai]https://nodes.griptape.ai[/link][/bold blue]",
+            ),
+            title="[red]X[/red] Connection Failed",
+            border_style="red",
+            padding=(1, 4),
+        )
+        console.print(message)
+        sys.exit(1)
     except Exception as e:
         logger.error("WebSocket thread error: %s", e)
         raise

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/exe_types/param_components/execution_status_component.py

@@ -103,8 +103,16 @@ class ExecutionStatusComponent:
         """
         self._update_parameter_value(self._was_successful, was_successful)
         self._update_parameter_value(self._result_details, result_details)
-        # Update display label: show warning emoji on failure
-        self._update_status_group_display_label(show_warning=not was_successful)
+        # Update display label: show warning emoji only on actual failure (not placeholder/initialization messages)
+        # While string matching is not the best practice, it's currently the only way to check for placeholder messages.
+        # TODO: use a better approach to check for placeholder messages. https://github.com/griptape-ai/griptape-nodes/issues/3686
+        is_placeholder = result_details in (
+            "<Results will appear when the node executes>",
+            "Beginning execution...",
+            "",
+        )
+        show_warning = not was_successful and not is_placeholder
+        self._update_status_group_display_label(show_warning=show_warning)
 
     def clear_execution_status(self, initial_message: str | None = None) -> None:
         """Clear execution status and reset parameters.

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/exe_types/param_components/log_parameter.py

@@ -20,7 +20,7 @@ class LogParameter:
                 output_type="str",
                 allowed_modes={ParameterMode.OUTPUT},
                 tooltip="logs",
-                ui_options={"multiline": True},
+                ui_options={"multiline": True, "placeholder_text": ""},
             )
         )
 
@@ -68,6 +68,10 @@ class StdoutCapture:
     def flush(self) -> None:
         self._original_stdout.flush()
 
+    def isatty(self) -> bool:
+        # Return False to prevent libraries from outputting ANSI color codes
+        return False
+
     def __enter__(self) -> "StdoutCapture":
         sys.stdout = self
         return self

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/exe_types/param_types/parameter_number.py

@@ -235,12 +235,6 @@ class ParameterNumber(Parameter):
             validate_min_max: Whether to validate min/max with error
         """
         # Validation rules
-        if min_val is not None and max_val is None:
-            msg = f"{name}: If min_val is provided, max_val must also be provided"
-            raise ValueError(msg)
-        if max_val is not None and min_val is None:
-            msg = f"{name}: If max_val is provided, min_val must also be provided"
-            raise ValueError(msg)
         if slider and (min_val is None or max_val is None):
             msg = f"{name}: If slider is True, both min_val and max_val must be provided"
             raise ValueError(msg)
@@ -259,7 +253,7 @@ class ParameterNumber(Parameter):
             traits.add(Slider(min_val=min_val, max_val=max_val))
         elif validate_min_max and min_val is not None and max_val is not None:
             traits.add(MinMax(min_val=min_val, max_val=max_val))
-        elif min_val is not None and max_val is not None:
+        elif min_val is not None or max_val is not None:
             traits.add(Clamp(min_val=min_val, max_val=max_val))
 
         # Store traits for later use
@@ -304,9 +298,6 @@ class ParameterNumber(Parameter):
     @min_val.setter
     def min_val(self, value: float | None) -> None:
         """Set minimum value and update constraint traits."""
-        if value is not None and self.max_val is None:
-            msg = f"{self.name}: Cannot set min_val without max_val"
-            raise ValueError(msg)
         self._min_val = value
         self._update_constraint_traits()
 
@@ -321,9 +312,6 @@ class ParameterNumber(Parameter):
     @max_val.setter
     def max_val(self, value: float | None) -> None:
         """Set maximum value and update constraint traits."""
-        if value is not None and self.min_val is None:
-            msg = f"{self.name}: Cannot set max_val without min_val"
-            raise ValueError(msg)
         self._max_val = value
         self._update_constraint_traits()
 
@@ -367,17 +355,35 @@ class ParameterNumber(Parameter):
         min_val = getattr(self, "_min_val", None)
         max_val = getattr(self, "_max_val", None)
 
-        if min_val is None or max_val is None:
+        if min_val is None and max_val is None:
             self._remove_constraint_traits()
             return
 
+        if self.slider and (min_val is None or max_val is None):
+            msg = f"{self.name}: Cannot enable slider without min_val and max_val"
+            raise ValueError(msg)
+
+        if self.validate_min_max and (min_val is None or max_val is None):
+            msg = f"{self.name}: Cannot enable validate_min_max without min_val and max_val"
+            raise ValueError(msg)
+
         # Determine which trait to use based on current state
         if self.slider:
+            # Checked above: both min_val and max_val are available when slider is enabled.
+            # Type narrowing: assign to variables after None check so type checker understands
+            min_val_float: float = min_val  # type: ignore[assignment]
+            max_val_float: float = max_val  # type: ignore[assignment]
+            # Python will naturally coerce int to float if needed (no precision loss for reasonable values)
             self._remove_constraint_traits()
-            self.add_trait(Slider(min_val=min_val, max_val=max_val))
+            self.add_trait(Slider(min_val=min_val_float, max_val=max_val_float))
         elif self.validate_min_max:
+            # Checked above: both min_val and max_val are available when validate_min_max is enabled.
+            # Type narrowing: assign to variables after None check so type checker understands
+            min_val_float: float = min_val  # type: ignore[assignment]
+            max_val_float: float = max_val  # type: ignore[assignment]
+            # Python will naturally coerce int to float if needed (no precision loss for reasonable values)
             self._remove_constraint_traits()
-            self.add_trait(MinMax(min_val=min_val, max_val=max_val))
+            self.add_trait(MinMax(min_val=min_val_float, max_val=max_val_float))
         else:
             self._remove_constraint_traits()
             self.add_trait(Clamp(min_val=min_val, max_val=max_val))

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/retained_mode/events/node_events.py

@@ -564,6 +564,7 @@ class SerializeNodeToCommandsRequest(RequestPayload):
     serialized_parameter_value_tracker: SerializedParameterValueTracker = field(
         default_factory=SerializedParameterValueTracker
     )
+    use_pickling: bool = False
 
 
 @dataclass
@@ -648,7 +649,8 @@ class SerializeSelectedNodesToCommandsResultSuccess(WorkflowNotAlteredMixin, Res
 
     # They will be passed with node_name, timestamp
     # Could be a flow command if it's all nodes in a flow.
-    serialized_selected_node_commands: SerializedSelectedNodesCommands
+    serialized_selected_node_commands: str
+    pickled_values: dict[str, str]
 
 
 @dataclass
@@ -674,6 +676,8 @@ class DeserializeSelectedNodesFromCommandsRequest(WorkflowNotAlteredMixin, Reque
     Results: DeserializeSelectedNodesFromCommandsResultSuccess (with node names) | DeserializeSelectedNodesFromCommandsResultFailure (deserialization error)
     """
 
+    deserialize_commands: str
+    pickled_values: dict[str, str]
     positions: list[NewPosition] | None = None
 
 

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/retained_mode/managers/context_manager.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
 from griptape_nodes.exe_types.flow import ControlFlow
 from griptape_nodes.retained_mode.events.context_events import (
@@ -18,8 +18,6 @@ if TYPE_CHECKING:
     from griptape_nodes.exe_types.core_types import BaseNodeElement
     from griptape_nodes.exe_types.node_types import BaseNode
     from griptape_nodes.retained_mode.events.base_events import ResultPayload
-    from griptape_nodes.retained_mode.events.flow_events import SerializedFlowCommands
-    from griptape_nodes.retained_mode.events.node_events import SerializedSelectedNodesCommands
     from griptape_nodes.retained_mode.managers.event_manager import EventManager
 
 logger = logging.getLogger("griptape_nodes")
@@ -34,7 +32,6 @@ class ContextManager:
     """
 
     _workflow_stack: list[ContextManager.WorkflowContextState]
-    _clipboard: ClipBoard
 
     class WorkflowContextError(Exception):
         """Base exception for workflow context errors."""
@@ -242,32 +239,9 @@ class ContextManager:
         ) -> None:
             self._manager.pop_element()
 
-    class ClipBoard:
-        """Keeps Commands for Copying or Pasting."""
-
-        # Contains flow, node, parameter, connections
-        flow_commands: SerializedFlowCommands | None
-        # Contains node and Parameter and relevant connections
-        node_commands: SerializedSelectedNodesCommands | None
-        parameter_uuid_to_values: dict[str, Any] | None
-
-        def __init__(self) -> None:
-            self.flow_commands = None
-            self.node_commands = None
-            self.parameter_uuid_to_values = None
-
-        def clear(self) -> None:
-            del self.flow_commands
-            self.flow_commands = None
-            del self.node_commands
-            self.node_commands = None
-            if self.parameter_uuid_to_values is not None:
-                self.parameter_uuid_to_values.clear()
-
     def __init__(self, event_manager: EventManager) -> None:
         """Initialize the context manager with empty workflow and flow stacks."""
         self._workflow_stack = []
-        self._clipboard = self.ClipBoard()
         event_manager.assign_manager_to_request_type(
             request_type=SetWorkflowContextRequest, callback=self.on_set_workflow_context_request
         )

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/retained_mode/managers/node_manager.py

@@ -2781,6 +2781,7 @@ class NodeManager:
                     unique_parameter_uuid_to_values=request.unique_parameter_uuid_to_values,
                     serialized_parameter_value_tracker=request.serialized_parameter_value_tracker,
                     create_node_request=create_node_request,
+                    use_pickling=request.use_pickling,
                 )
                 if set_param_value_requests is not None:
                     set_value_commands.extend(set_param_value_requests)
@@ -2983,6 +2984,7 @@ class NodeManager:
                     node_name=node_name,
                     unique_parameter_uuid_to_values=unique_uuid_to_values,
                     serialized_parameter_value_tracker=serialized_parameter_value_tracker,
+                    use_pickling=True,
                 )
             )
             if not isinstance(result, SerializeNodeToCommandsResultSuccess):
@@ -3029,22 +3031,55 @@ class NodeManager:
             set_parameter_value_commands=parameter_commands,
             set_lock_commands_per_node=lock_commands,
         )
-        # Set everything in the clipboard if requested
-        if request.copy_to_clipboard:
-            GriptapeNodes.ContextManager()._clipboard.node_commands = final_result
-            GriptapeNodes.ContextManager()._clipboard.parameter_uuid_to_values = unique_uuid_to_values
+
+        # Encode pickled bytes to latin-1 strings for JSON serialization
+        encoded_values = {}
+        for uuid, value in unique_uuid_to_values.items():
+            if isinstance(value, bytes):
+                # Pickled bytes - encode as latin-1 string for transport
+                encoded_values[uuid] = value.decode("latin1")
+            else:
+                # Non-pickled value - keep as-is (for backward compatibility)
+                encoded_values[uuid] = value
+
+        # Pickle the commands object and encode as latin-1 string for transport
+        pickled_commands_bytes = pickle.dumps(final_result)
+        pickled_commands_string = pickled_commands_bytes.decode("latin1")
         return SerializeSelectedNodesToCommandsResultSuccess(
-            final_result,
+            pickled_commands_string,  # Send pickled string instead of object
+            pickled_values=encoded_values,
             result_details=f"Successfully serialized {len(request.nodes_to_serialize)} selected nodes to commands.",
         )
 
-    def on_deserialize_selected_nodes_from_commands(  # noqa: C901, PLR0912
+    def on_deserialize_selected_nodes_from_commands(  # noqa: C901, PLR0912, PLR0915
         self,
         request: DeserializeSelectedNodesFromCommandsRequest,
     ) -> ResultPayload:
-        commands = GriptapeNodes.ContextManager()._clipboard.node_commands
-        if commands is None:
-            return DeserializeSelectedNodesFromCommandsResultFailure(result_details="No Node Commands Found")
+        # Decode latin-1 encoded pickled strings back to Python objects
+        decoded_values = {}
+        if request.pickled_values:
+            for uuid, latin1_string in request.pickled_values.items():
+                if isinstance(latin1_string, str):
+                    try:
+                        # Decode: latin-1 string → bytes → unpickled object
+                        pickled_bytes = latin1_string.encode("latin1")
+                        decoded_values[uuid] = pickle.loads(pickled_bytes)  # noqa: S301 Expecting this from the GUI.
+                    except Exception:
+                        details = f"Failed to unpickle parameter value for UUID {uuid}"
+                        logger.warning(details)
+                        # Keep original value if unpickling fails
+                        decoded_values[uuid] = latin1_string
+                else:
+                    # Not a string, keep as-is
+                    decoded_values[uuid] = latin1_string
+
+        # Unpickle the commands string into SerializedSelectedNodesCommands
+        try:
+            pickled_commands_bytes = request.deserialize_commands.encode("latin1")
+            commands = pickle.loads(pickled_commands_bytes)  # noqa: S301 Expecting this from the GUI.
+        except Exception as e:
+            details = f"Failed to unpickle commands: {e}"
+            return DeserializeSelectedNodesFromCommandsResultFailure(result_details=details)
         connections = commands.serialized_connection_commands
         node_uuid_to_name = {}
         # Enumerate because positions is in the same order as the node commands.
@@ -3078,10 +3113,9 @@ class NodeManager:
                     param_request = parameter_command.set_parameter_value_command
                     # Set the Node name
                     param_request.node_name = result.node_name
-                    # Set the new value
-                    table = GriptapeNodes.ContextManager()._clipboard.parameter_uuid_to_values
-                    if table and parameter_command.unique_value_uuid in table:
-                        value = table[parameter_command.unique_value_uuid]
+                    # Set the new value from decoded_values
+                    if decoded_values and parameter_command.unique_value_uuid in decoded_values:
+                        value = decoded_values[parameter_command.unique_value_uuid]
                         # Using try-except-pass instead of contextlib.suppress because it's clearer.
                         try:  # noqa: SIM105
                             # If we're pasting multiple times - we need to create a new copy for each paste so they don't all have the same reference.
@@ -3119,13 +3153,20 @@ class NodeManager:
         )
 
     def on_duplicate_selected_nodes(self, request: DuplicateSelectedNodesRequest) -> ResultPayload:
-        result = GriptapeNodes.handle_request(
+        serialize_result = GriptapeNodes.handle_request(
             SerializeSelectedNodesToCommandsRequest(nodes_to_serialize=request.nodes_to_duplicate)
         )
-        if result.failed():
+        if not isinstance(serialize_result, SerializeSelectedNodesToCommandsResultSuccess):
             details = "Failed to serialized selected nodes."
             return DuplicateSelectedNodesResultFailure(result_details=details)
-        result = GriptapeNodes.handle_request(DeserializeSelectedNodesFromCommandsRequest(positions=request.positions))
+
+        # Pass the pickled commands and values to deserialization
+        deserialize_request = DeserializeSelectedNodesFromCommandsRequest(
+            deserialize_commands=serialize_result.serialized_selected_node_commands,
+            pickled_values=serialize_result.pickled_values,
+            positions=request.positions,
+        )
+        result = GriptapeNodes.handle_request(deserialize_request)
         if not isinstance(result, DeserializeSelectedNodesFromCommandsResultSuccess):
             details = "Failed to deserialize selected nodes."
             return DuplicateSelectedNodesResultFailure(result_details=details)
@@ -3177,6 +3218,7 @@ class NodeManager:
         node_name: str,
         *,
         is_output: bool,
+        use_pickling: bool = False,
     ) -> SerializedNodeCommands.IndirectSetParameterValueCommand | None:
         try:
             hash(value)
@@ -3211,12 +3253,20 @@ class NodeManager:
                     return None
                 # The value should be serialized. Add it to the map of uniques.
                 unique_uuid = SerializedNodeCommands.UniqueParameterValueUUID(str(uuid4()))
-                try:
-                    unique_parameter_uuid_to_values[unique_uuid] = copy.deepcopy(value)
-                except Exception:
-                    details = f"Attempted to serialize parameter '{parameter_name}` on node '{node_name}'. The parameter value could not be copied. It will be serialized by value. If problems arise from this, ensure the type '{type(value)}' works with copy.deepcopy()."
-                    logger.warning(details)
-                    unique_parameter_uuid_to_values[unique_uuid] = value
+
+                if use_pickling:
+                    # Use pickle serialization via WorkflowManager
+                    workflow_manager = GriptapeNodes.WorkflowManager()
+                    pickled_bytes = workflow_manager._patch_and_pickle_object(value)
+                    unique_parameter_uuid_to_values[unique_uuid] = pickled_bytes
+                else:
+                    # Use existing deep copy approach
+                    try:
+                        unique_parameter_uuid_to_values[unique_uuid] = copy.deepcopy(value)
+                    except Exception:
+                        details = f"Attempted to serialize parameter '{parameter_name}` on node '{node_name}'. The parameter value could not be copied. It will be serialized by value. If problems arise from this, ensure the type '{type(value)}' works with copy.deepcopy()."
+                        logger.warning(details)
+                        unique_parameter_uuid_to_values[unique_uuid] = value
                 serialized_parameter_value_tracker.add_as_serializable(value_id, unique_uuid)
 
         # Serialize it
@@ -3233,12 +3283,14 @@ class NodeManager:
         return indirect_set_value_command
 
     @staticmethod
-    def handle_parameter_value_saving(
+    def handle_parameter_value_saving(  # noqa: PLR0913
         parameter: Parameter,
         node: BaseNode,
         unique_parameter_uuid_to_values: dict[SerializedNodeCommands.UniqueParameterValueUUID, Any],
         serialized_parameter_value_tracker: SerializedParameterValueTracker,
         create_node_request: CreateNodeRequest,
+        *,
+        use_pickling: bool = False,
     ) -> list[SerializedNodeCommands.IndirectSetParameterValueCommand] | None:
         """Generates code to save a parameter value for a node in a Griptape workflow.
 
@@ -3256,6 +3308,7 @@ class NodeManager:
             unique_parameter_uuid_to_values (dict[SerializedNodeCommands.UniqueParameterValueUUID, Any]): Dictionary mapping unique value UUIDs to values
             serialized_parameter_value_tracker (SerializedParameterValueTracker): Object mapping maintaining value hashes to unique value UUIDs, and non-serializable values
             create_node_request (CreateNodeRequest): The node creation request that will be modified if serialization fails
+            use_pickling (bool): If True, use pickle-based serialization; if False, use deep copy
 
         Returns:
             None (if no value to be serialized) or an IndirectSetParameterValueCommand linking the value to the unique value map
@@ -3292,6 +3345,7 @@ class NodeManager:
                 is_output=False,
                 parameter_name=parameter.name,
                 node_name=node.name,
+                use_pickling=use_pickling,
             )
             if internal_command is None:
                 details = f"Attempted to serialize set value for parameter '{parameter.name}' on node '{node.name}'. The set value will not be restored in anything that attempts to deserialize or save this node. The value for this parameter was not serialized because it did not match Griptape Nodes' criteria for serializability. To remedy, either update the value's type to support serializability or mark the parameter as not serializable by setting serializable=False when creating the parameter."
@@ -3310,6 +3364,7 @@ class NodeManager:
                 is_output=True,
                 parameter_name=parameter.name,
                 node_name=node.name,
+                use_pickling=use_pickling,
             )
             if output_command is None:
                 details = f"Attempted to serialize output value for parameter '{parameter.name}' on node '{node.name}'. The output value will not be restored in anything that attempts to deserialize or save this node. The value for this parameter was not serialized because it did not match Griptape Nodes' criteria for serializability. To remedy, either update the value's type to support serializability or mark the parameter as not serializable by setting serializable=False when creating the parameter."

{griptape_nodes-0.69.0 → griptape_nodes-0.70.1}/src/griptape_nodes/retained_mode/managers/object_manager.py

@@ -149,7 +149,6 @@ class ObjectManager:
                     context_mgr.pop_node()
                 context_mgr.pop_flow()
             context_mgr.pop_workflow()
-        context_mgr._clipboard.clear()
 
         # Clear all local workflow variables
         GriptapeNodes.VariablesManager().on_clear_object_state()

griptape_nodes-0.70.1/src/griptape_nodes/traits/clamp.py

@@ -0,0 +1,79 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from griptape_nodes.exe_types.core_types import Trait
+
+
+@dataclass(eq=False)
+class Clamp(Trait):
+    min: Any = 0
+    max: Any = 10
+    element_id: str = field(default_factory=lambda: "ClampTrait")
+
+    def __init__(self, min_val: float | None = None, max_val: float | None = None) -> None:
+        super().__init__()
+        self.min = min_val
+        self.max = max_val
+
+    @classmethod
+    def get_trait_keys(cls) -> list[str]:
+        return ["clamp"]
+
+    def _clamp_number(self, value: float) -> float:
+        # Keep this as a tiny helper so the converter stays readable and so we can
+        # consistently apply one-sided bounds (min-only or max-only) everywhere.
+        if self.max is not None and value > self.max:
+            value = self.max
+        if self.min is not None and value < self.min:
+            value = self.min
+        return value
+
+    def _clamp_sequence(self, value: list[Any]) -> list[Any]:
+        # Clamp historically applied to strings/lists by max length; we keep list handling
+        # explicit here so bounds semantics remain obvious.
+        if self.max is None:
+            return value
+        if len(value) <= self.max:
+            return value
+        return value[: self.max]
+
+    def _try_parse_numeric_string(self, value: str) -> float | None:
+        # Trait converters run BEFORE parameter-level converters (e.g. ParameterInt/Float
+        # parsing). That means UI inputs often arrive as strings here; to make min/max
+        # clamping actually work with typical UI inputs, we parse numeric strings when
+        # bounds are configured.
+        if self.min is None and self.max is None:
+            return None
+
+        stripped = value.strip()
+        if not stripped:
+            return None
+
+        try:
+            return float(stripped)
+        except ValueError:
+            return None
+
+    def converters_for_trait(self) -> list[Callable]:
+        def clamp(value: Any) -> Any:
+            if isinstance(value, list):
+                return self._clamp_sequence(value)
+
+            if isinstance(value, str):
+                parsed = self._try_parse_numeric_string(value)
+                if parsed is not None:
+                    return self._clamp_number(parsed)
+
+                # If it's not a numeric string (or no bounds configured), preserve the
+                # historical string behavior: max length clamping only.
+                if self.max is None or len(value) <= self.max:
+                    return value
+                return value[: self.max]
+
+            if isinstance(value, (int, float)):
+                return self._clamp_number(float(value))
+
+            return value
+
+        return [clamp]

griptape_nodes-0.69.0/src/griptape_nodes/traits/clamp.py

@@ -1,36 +0,0 @@
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import Any
-
-from griptape_nodes.exe_types.core_types import Trait
-
-
-@dataclass(eq=False)
-class Clamp(Trait):
-    min: Any = 0
-    max: Any = 10
-    element_id: str = field(default_factory=lambda: "ClampTrait")
-
-    def __init__(self, min_val: float, max_val: float) -> None:
-        super().__init__()
-        self.min = min_val
-        self.max = max_val
-
-    @classmethod
-    def get_trait_keys(cls) -> list[str]:
-        return ["clamp"]
-
-    def converters_for_trait(self) -> list[Callable]:
-        def clamp(value: Any) -> Any:
-            if isinstance(value, (str, list)):
-                if len(value) > self.max:
-                    return value[: self.max]
-                return value
-            if isinstance(value, (int, float)):
-                if value > self.max:
-                    return self.max
-                if value < self.min:
-                    return self.min
-            return value
-
-        return [clamp]