griptape-nodes 0.70.1__py3-none-any.whl → 0.72.0__py3-none-any.whl

griptape_nodes/exe_types/param_types/parameter_int.py

@@ -43,8 +43,8 @@ class ParameterInt(ParameterNumber):
         ui_options: dict | None = None,
         step: int | None = None,
         slider: bool = False,
-        min_val: float = 0,
-        max_val: float = 100,
+        min_val: float | None = None,
+        max_val: float | None = None,
         validate_min_max: bool = False,
         accept_any: bool = True,
         hide: bool | None = None,
@@ -77,8 +77,8 @@ class ParameterInt(ParameterNumber):
             ui_options: Dictionary of UI options
             step: Step size for numeric input controls
             slider: Whether to use slider trait
-            min_val: Minimum value for constraints
-            max_val: Maximum value for constraints
+            min_val: Minimum value for constraints (None to disable constraints)
+            max_val: Maximum value for constraints (None to disable constraints)
             validate_min_max: Whether to validate min/max with error
             accept_any: Whether to accept any input type and convert to integer (default: True)
             hide: Whether to hide the entire parameter

griptape_nodes/exe_types/param_types/parameter_number.py

@@ -37,8 +37,8 @@ class ParameterNumber(Parameter):
         ui_options: dict | None = None,
         step: float | None = None,
         slider: bool = False,
-        min_val: float = 0,
-        max_val: float = 100,
+        min_val: float | None = None,
+        max_val: float | None = None,
         validate_min_max: bool = False,
         accept_any: bool = True,
         hide: bool | None = None,
@@ -74,8 +74,8 @@ class ParameterNumber(Parameter):
             ui_options: Dictionary of UI options
             step: Step size for numeric input controls
             slider: Whether to use slider trait
-            min_val: Minimum value for constraints
-            max_val: Maximum value for constraints
+            min_val: Minimum value for constraints (None to disable constraints)
+            max_val: Maximum value for constraints (None to disable constraints)
             validate_min_max: Whether to validate min/max with error
             accept_any: Whether to accept any input type and convert to number (default: True)
             hide: Whether to hide the entire parameter
@@ -220,8 +220,8 @@ class ParameterNumber(Parameter):
         traits: set[type[Trait] | Trait] | None,
         *,
         slider: bool,
-        min_val: float,
-        max_val: float,
+        min_val: float | None,
+        max_val: float | None,
         validate_min_max: bool,
     ) -> None:
         """Set up constraint traits based on parameters.
@@ -272,14 +272,14 @@ class ParameterNumber(Parameter):
     def slider(self, value: bool) -> None:
         """Set slider trait."""
         if value:
-            if not hasattr(self, "_constraint_traits") or not self._constraint_traits:
+            # Get min/max from stored values
+            min_val = getattr(self, "_min_val", None)
+            max_val = getattr(self, "_max_val", None)
+            if 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)
             # Find existing constraint traits and replace with slider
             self._remove_constraint_traits()
-            # Get min/max from existing traits or use defaults
-            min_val = getattr(self, "_min_val", 0)
-            max_val = getattr(self, "_max_val", 100)
             self.add_trait(Slider(min_val=min_val, max_val=max_val))
         else:
             # Remove slider trait
@@ -325,14 +325,12 @@ class ParameterNumber(Parameter):
         """Set MinMax validation."""
         if value:
             # Check if we have stored min/max values
-            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 self.min_val is None or self.max_val is None:
                 msg = f"{self.name}: Cannot enable validate_min_max without min_val and max_val"
                 raise ValueError(msg)
             # Replace existing constraint traits with MinMax
             self._remove_constraint_traits()
-            self.add_trait(MinMax(min_val=min_val, max_val=max_val))
+            self.add_trait(MinMax(min_val=self.min_val, max_val=self.max_val))
         else:
             # Remove MinMax trait and replace with Clamp if we have min/max
             min_max_traits = self.find_elements_by_type(MinMax)

griptape_nodes/exe_types/param_types/parameter_three_d.py

@@ -3,7 +3,10 @@
 from collections.abc import Callable
 from typing import Any
 
+from griptape_nodes_library.three_d.three_d_artifact import ThreeDUrlArtifact  # pyright: ignore[reportMissingImports]
+
 from griptape_nodes.exe_types.core_types import Parameter, ParameterMode, Trait
+from griptape_nodes.utils.artifact_normalization import normalize_artifact_input
 
 
 class Parameter3D(Parameter):
@@ -117,6 +120,16 @@ class Parameter3D(Parameter):
         else:
             final_input_types = ["ThreeDUrlArtifact"]
 
+        # Add automatic converter to normalize string inputs to ThreeDUrlArtifact
+        # This allows Parameter3D to automatically handle file paths and localhost URLs
+        three_d_converters = list(converters) if converters else []
+        if accept_any:
+            # Create a converter function that uses normalize_artifact_input with ThreeDUrlArtifact
+            def _normalize_three_d(value: Any) -> Any:
+                return normalize_artifact_input(value, ThreeDUrlArtifact)
+
+            three_d_converters.insert(0, _normalize_three_d)
+
         # Call parent with explicit parameters, following ControlParameter pattern
         super().__init__(
             name=name,
@@ -130,7 +143,7 @@ class Parameter3D(Parameter):
             tooltip_as_output=tooltip_as_output,
             allowed_modes=allowed_modes,
             traits=traits,
-            converters=converters,
+            converters=three_d_converters,
             validators=validators,
             ui_options=ui_options,
             hide=hide,

griptape_nodes/exe_types/param_types/parameter_video.py

@@ -4,6 +4,7 @@ from collections.abc import Callable
 from typing import Any
 
 from griptape_nodes.exe_types.core_types import Parameter, ParameterMode, Trait
+from griptape_nodes.utils.artifact_normalization import normalize_artifact_input
 
 
 class ParameterVideo(Parameter):
@@ -24,7 +25,7 @@ class ParameterVideo(Parameter):
         param.pulse_on_run = True  # Change UI options at runtime
     """
 
-    def __init__(  # noqa: PLR0913
+    def __init__(  # noqa: C901, PLR0913
         self,
         name: str,
         tooltip: str | None = None,
@@ -122,6 +123,20 @@ class ParameterVideo(Parameter):
         else:
             final_input_types = ["VideoUrlArtifact"]
 
+        # Add automatic converter to normalize string inputs to VideoUrlArtifact
+        # This allows ParameterVideo to automatically handle file paths and localhost URLs
+        video_converters = list(converters) if converters else []
+        if accept_any:
+            # Create a converter function that uses normalize_artifact_input with VideoUrlArtifact
+            def _normalize_video(value: Any) -> Any:
+                try:
+                    from griptape.artifacts import VideoUrlArtifact
+                except ImportError:
+                    return value
+                return normalize_artifact_input(value, VideoUrlArtifact)
+
+            video_converters.insert(0, _normalize_video)
+
         # Call parent with explicit parameters, following ControlParameter pattern
         super().__init__(
             name=name,
@@ -135,7 +150,7 @@ class ParameterVideo(Parameter):
             tooltip_as_output=tooltip_as_output,
             allowed_modes=allowed_modes,
             traits=traits,
-            converters=converters,
+            converters=video_converters,
             validators=validators,
             ui_options=ui_options,
             hide=hide,

griptape_nodes/node_library/workflow_registry.py

@@ -12,6 +12,7 @@ from griptape_nodes.node_library.library_registry import (
     LibraryNameAndVersion,  # noqa: TC001 (putting this into type checking causes it to not be defined)
 )
 from griptape_nodes.utils.metaclasses import SingletonMeta
+from griptape_nodes.utils.path_utils import resolve_workspace_path
 
 logger = logging.getLogger("griptape_nodes")
 
@@ -45,7 +46,7 @@ class WorkflowShape(BaseModel):
 
 
 class WorkflowMetadata(BaseModel):
-    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.14.0"
+    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.15.0"
 
     name: str
     schema_version: str
@@ -175,15 +176,11 @@ class WorkflowRegistry(metaclass=SingletonMeta):
     def get_complete_file_path(cls, relative_file_path: str) -> str:
         from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
-        # If the path is already absolute, return it as-is
-        if Path(relative_file_path).is_absolute():
-            return relative_file_path
-
-        # Otherwise, resolve it relative to the workspace
+        # Resolve path using utility function
         config_mgr = GriptapeNodes.ConfigManager()
         workspace_path = config_mgr.workspace_path
-        complete_file_path = workspace_path / relative_file_path
-        return str(complete_file_path)
+        resolved_path = resolve_workspace_path(Path(relative_file_path), workspace_path)
+        return str(resolved_path)
 
     @classmethod
     def delete_workflow_by_name(cls, name: str) -> Workflow:

griptape_nodes/retained_mode/events/app_events.py

@@ -113,6 +113,7 @@ class AppInitializationComplete(AppPayload):
     libraries_to_register: list[str] = field(default_factory=list)
     workflows_to_register: list[str] = field(default_factory=list)
     models_to_download: list[str] = field(default_factory=list)
+    skip_library_loading: bool = False
 
 
 @dataclass

griptape_nodes/retained_mode/events/base_events.py

@@ -16,6 +16,31 @@ if TYPE_CHECKING:
     import builtins
 
 
+def default_json_encoder(obj: Any) -> Any:
+    """Custom JSON encoder for various object types.
+
+    Attempts the following encodings in order:
+    1. If the object is a SerializableMixin, call to_dict()
+    2. If the object is a Pydantic model, call model_dump()
+    3. Attempt to use the default JSON encoder
+    4. If all else fails, return the string representation of the object
+
+    Args:
+        obj: The object to encode
+
+    Returns:
+        JSON-serializable representation of the object
+    """
+    if isinstance(obj, SerializableMixin):
+        return obj.to_dict()
+    if isinstance(obj, BaseModel):
+        return obj.model_dump()
+    try:
+        return json.JSONEncoder().default(obj)
+    except TypeError:
+        return str(obj)
+
+
 @dataclass
 class ResultDetail:
     """A single detail about an operation result, including logging level and human readable message."""
@@ -71,6 +96,22 @@ class ResultDetails:
 class Payload(ABC):  # noqa: B024
     """Base class for all payload types. Customers will derive from this."""
 
+    def to_json(self, **kwargs) -> str:
+        """Serialize this payload to JSON string.
+
+        Returns:
+            JSON string representation of the payload
+        """
+        # Convert payload to dict
+        if is_dataclass(self):
+            payload_dict = asdict(self)
+        elif hasattr(self, "__dict__"):
+            payload_dict = self.__dict__
+        else:
+            payload_dict = str(self)
+
+        return json.dumps(payload_dict, default=default_json_encoder, **kwargs)
+
 
 # Request payload base class with optional request ID
 @dataclass(kw_only=True)
@@ -228,32 +269,7 @@ class BaseEvent(BaseModel, ABC):
 
     def json(self, **kwargs) -> str:
         """Serialize to JSON string."""
-
-        # TODO: https://github.com/griptape-ai/griptape-nodes/issues/906
-        def default_encoder(obj: Any) -> Any:
-            """Custom JSON encoder for various object types.
-
-            Attempts the following encodings in order:
-            1. If the object is a SerializableMixin, call to_dict()
-            2. If the object is a Pydantic model, call model_dump()
-            3. Attempt to use the default JSON encoder
-            4. If all else fails, return the string representation of the object
-
-            Args:
-                obj: The object to encode
-
-
-            """
-            if isinstance(obj, SerializableMixin):
-                return obj.to_dict()
-            if isinstance(obj, BaseModel):
-                return obj.model_dump()
-            try:
-                return json.JSONEncoder().default(obj)
-            except TypeError:
-                return str(obj)
-
-        return json.dumps(self.dict(), default=default_encoder, **kwargs)
+        return json.dumps(self.dict(), default=default_json_encoder, **kwargs)
 
     @abstractmethod
     def get_request(self) -> Payload:

griptape_nodes/retained_mode/events/flow_events.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from enum import StrEnum
 from typing import TYPE_CHECKING, Any, NamedTuple
 
 if TYPE_CHECKING:
@@ -19,6 +20,18 @@ from griptape_nodes.retained_mode.events.base_events import (
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
 
+class FlowMetadataExtractionFailureReason(StrEnum):
+    """Reasons why flow metadata extraction from image failed."""
+
+    FILE_NOT_FOUND = "file_not_found"
+    FILE_READ_ERROR = "file_read_error"
+    INVALID_IMAGE_FORMAT = "invalid_image_format"
+    NO_FLOW_METADATA = "no_flow_metadata"
+    INVALID_BASE64 = "invalid_base64"
+    INVALID_PICKLE = "invalid_pickle"
+    DESERIALIZATION_FAILED = "deserialization_failed"
+
+
 @dataclass(kw_only=True)
 @PayloadRegistry.register
 class CreateFlowRequest(RequestPayload):
@@ -288,6 +301,60 @@ class DeserializeFlowFromCommandsResultFailure(ResultPayloadFailure):
     pass
 
 
+@dataclass
+@PayloadRegistry.register
+class ExtractFlowCommandsFromImageMetadataRequest(RequestPayload):
+    """Extract flow commands from PNG image metadata.
+
+    This request reads a PNG image file, extracts the embedded workflow metadata
+    (specifically the gtn_flow_commands field), decodes it from base64, unpickles it,
+    and returns the SerializedFlowCommands object. Optionally, it can automatically
+    deserialize the flow by calling DeserializeFlowFromCommandsRequest.
+
+    Use when: Loading flow commands from an exported image, inspecting workflow
+    structure before deserialization, extracting flows shared as PNG files.
+
+    Args:
+        file_url_or_path: Path to the PNG image file (absolute or relative) or URL
+        deserialize: If True, automatically deserialize the flow after extraction (default: False)
+
+    Results:
+        ExtractFlowCommandsFromImageMetadataResultSuccess - Commands extracted (and optionally deserialized)
+        ExtractFlowCommandsFromImageMetadataResultFailure - Extraction or deserialization failed
+    """
+
+    file_url_or_path: str
+    deserialize: bool = False
+
+
+@dataclass(kw_only=True)
+@PayloadRegistry.register
+class ExtractFlowCommandsFromImageMetadataResultSuccess(ResultPayloadSuccess):
+    """Flow commands extracted successfully from image metadata.
+
+    Args:
+        serialized_flow_commands: The extracted and decoded SerializedFlowCommands object
+        flow_name: Name of the deserialized flow (only present if deserialize=True)
+        node_name_mappings: Mapping from original to deserialized node names (only present if deserialize=True)
+    """
+
+    serialized_flow_commands: SerializedFlowCommands
+    flow_name: str | None = None
+    node_name_mappings: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+@PayloadRegistry.register
+class ExtractFlowCommandsFromImageMetadataResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Flow commands extraction failed.
+
+    Args:
+        file_path: The file path that was attempted (for error context)
+    """
+
+    file_path: str
+
+
 @dataclass
 @PayloadRegistry.register
 class GetFlowDetailsRequest(RequestPayload):

griptape_nodes/retained_mode/events/library_events.py

@@ -607,7 +607,7 @@ class DiscoverLibrariesRequest(RequestPayload):
 class DiscoverLibrariesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
     """Libraries discovered successfully."""
 
-    libraries_discovered: set[DiscoveredLibrary]  # Discovered libraries with type info
+    libraries_discovered: list[DiscoveredLibrary]  # Discovered libraries in config order
 
 
 @dataclass

griptape_nodes/retained_mode/events/node_events.py

@@ -565,6 +565,7 @@ class SerializeNodeToCommandsRequest(RequestPayload):
         default_factory=SerializedParameterValueTracker
     )
     use_pickling: bool = False
+    serialize_all_parameter_values: bool = False
 
 
 @dataclass

griptape_nodes/retained_mode/events/os_events.py

@@ -54,6 +54,24 @@ class FileIOFailureReason(StrEnum):
     IO_ERROR = "io_error"  # Generic I/O error
     UNKNOWN = "unknown"  # Unexpected error
 
+    # Recycle bin errors
+    RECYCLE_BIN_UNAVAILABLE = "recycle_bin_unavailable"  # Recycle bin unavailable and behavior was RECYCLE_BIN_ONLY
+
+
+class DeletionBehavior(StrEnum):
+    """How to handle file/directory deletion."""
+
+    PERMANENTLY_DELETE = "permanently_delete"  # Permanently delete (default, current behavior)
+    RECYCLE_BIN_ONLY = "recycle_bin_only"  # Send to recycle bin; fail if unavailable
+    PREFER_RECYCLE_BIN = "prefer_recycle_bin"  # Try recycle bin; fall back to permanent deletion
+
+
+class DeletionOutcome(StrEnum):
+    """The actual outcome of a deletion operation."""
+
+    PERMANENTLY_DELETED = "permanently_deleted"
+    SENT_TO_RECYCLE_BIN = "sent_to_recycle_bin"
+
 
 @dataclass
 class FileSystemEntry:
@@ -585,6 +603,7 @@ class DeleteFileRequest(RequestPayload):
         path: Path to file/directory to delete (mutually exclusive with file_entry)
         file_entry: FileSystemEntry from directory listing (mutually exclusive with path)
         workspace_only: If True, constrain to workspace directory
+        deletion_behavior: How to handle deletion (permanent, recycle bin only, or prefer recycle bin)
 
     Results: DeleteFileResultSuccess | DeleteFileResultFailure
     """
@@ -592,6 +611,7 @@ class DeleteFileRequest(RequestPayload):
     path: str | None = None
     file_entry: FileSystemEntry | None = None
     workspace_only: bool | None = True
+    deletion_behavior: DeletionBehavior = DeletionBehavior.PREFER_RECYCLE_BIN
 
 
 @dataclass
@@ -603,11 +623,13 @@ class DeleteFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
         deleted_path: The absolute path that was deleted (primary path)
         was_directory: Whether the deleted item was a directory
         deleted_paths: List of all paths that were deleted (for recursive deletes, includes all files/dirs)
+        outcome: The actual outcome of the deletion (permanently deleted or sent to recycle bin)
     """
 
     deleted_path: str
     was_directory: bool
     deleted_paths: list[str]
+    outcome: DeletionOutcome
 
 
 @dataclass

griptape_nodes/retained_mode/events/static_file_events.py

@@ -78,11 +78,13 @@ class CreateStaticFileUploadUrlResultSuccess(WorkflowNotAlteredMixin, ResultPayl
         url: Presigned URL for uploading the file
         headers: HTTP headers required for the upload request
         method: HTTP method to use for upload (typically PUT)
+        file_url: File URI (file://) for the absolute path where the file will be accessible after upload
     """
 
     url: str
     headers: dict = field(default_factory=dict)
     method: str = "PUT"
+    file_url: str = ""
 
 
 @dataclass
@@ -100,13 +102,13 @@ class CreateStaticFileUploadUrlResultFailure(WorkflowNotAlteredMixin, ResultPayl
 @dataclass
 @PayloadRegistry.register
 class CreateStaticFileDownloadUrlRequest(RequestPayload):
-    """Create a presigned URL for downloading a static file via HTTP GET.
+    """Create a presigned URL for downloading a static file from the staticfiles directory via HTTP GET.
 
-    Use when: Providing secure file access, implementing file sharing,
-    enabling temporary download links, controlling file access permissions.
+    Use when: Providing secure file access to files in the staticfiles directory,
+    implementing file sharing, enabling temporary download links, controlling file access permissions.
 
     Args:
-        file_name: Name of the file to be downloaded
+        file_name: Name of the file to be downloaded from the staticfiles directory
 
     Results: CreateStaticFileDownloadUrlResultSuccess (with URL) | CreateStaticFileDownloadUrlResultFailure (URL creation error)
     """
@@ -114,6 +116,26 @@ class CreateStaticFileDownloadUrlRequest(RequestPayload):
     file_name: str
 
 
+@dataclass
+@PayloadRegistry.register
+class CreateStaticFileDownloadUrlFromPathRequest(RequestPayload):
+    """Create a presigned URL for downloading a file from an arbitrary path.
+
+    Use when: Need to create download URLs for files outside the staticfiles directory,
+    working with absolute paths, file:// URLs, or workspace-relative paths.
+
+    Args:
+        file_path: File path or URL. Accepts:
+                   - file:// URLs (e.g., "file:///absolute/path/to/file.jpg")
+                   - Absolute paths (e.g., "/absolute/path/to/file.jpg")
+                   - Workspace-relative paths (e.g., "relative/path/to/file.jpg")
+
+    Results: CreateStaticFileDownloadUrlResultSuccess (with URL) | CreateStaticFileDownloadUrlResultFailure (URL creation error)
+    """
+
+    file_path: str
+
+
 @dataclass
 @PayloadRegistry.register
 class CreateStaticFileDownloadUrlResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
@@ -121,9 +143,11 @@ class CreateStaticFileDownloadUrlResultSuccess(WorkflowNotAlteredMixin, ResultPa
 
     Args:
         url: Presigned URL for downloading the file
+        file_url: File URI (file://) for the absolute path to the file that was used to create the download URL
     """
 
     url: str
+    file_url: str = ""
 
 
 @dataclass