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

griptape_nodes/drivers/storage/base_storage_driver.py

@@ -1,5 +1,6 @@
 import logging
 from abc import ABC, abstractmethod
+from pathlib import Path
 from typing import TypedDict
 
 import httpx
@@ -18,12 +19,31 @@ class CreateSignedUploadUrlResponse(TypedDict):
 class BaseStorageDriver(ABC):
     """Base class for storage drivers."""
 
+    def __init__(self, workspace_directory: Path) -> None:
+        """Initialize the storage driver with a workspace directory.
+
+        Args:
+            workspace_directory: The base workspace directory path.
+        """
+        self.workspace_directory = workspace_directory
+
+    def _get_full_path(self, path: Path) -> Path:
+        """Get the full path by joining workspace directory with the given path.
+
+        Args:
+            path: The relative path to join with workspace directory.
+
+        Returns:
+            The full path as workspace_directory / path.
+        """
+        return self.workspace_directory / path
+
     @abstractmethod
-    def create_signed_upload_url(self, file_name: str) -> CreateSignedUploadUrlResponse:
-        """Create a signed upload URL for the given file name.
+    def create_signed_upload_url(self, path: Path) -> CreateSignedUploadUrlResponse:
+        """Create a signed upload URL for the given path.
 
         Args:
-            file_name: The name of the file to create a signed URL for.
+            path: The path of the file to create a signed URL for.
 
         Returns:
             CreateSignedUploadUrlResponse: A dictionary containing the signed URL, headers, and operation type.
@@ -31,11 +51,11 @@ class BaseStorageDriver(ABC):
         ...
 
     @abstractmethod
-    def create_signed_download_url(self, file_name: str) -> str:
-        """Create a signed download URL for the given file name.
+    def create_signed_download_url(self, path: Path) -> str:
+        """Create a signed download URL for the given path.
 
         Args:
-            file_name: The name of the file to create a signed URL for.
+            path: The path of the file to create a signed URL for.
 
         Returns:
             str: The signed URL for downloading the file.
@@ -43,11 +63,11 @@ class BaseStorageDriver(ABC):
         ...
 
     @abstractmethod
-    def delete_file(self, file_name: str) -> None:
+    def delete_file(self, path: Path) -> None:
         """Delete a file from storage.
 
         Args:
-            file_name: The name of the file to delete.
+            path: The path of the file to delete.
         """
         ...
 
@@ -60,11 +80,11 @@ class BaseStorageDriver(ABC):
         """
         ...
 
-    def upload_file(self, file_name: str, file_content: bytes) -> str:
+    def upload_file(self, path: Path, file_content: bytes) -> str:
         """Upload a file to storage.
 
         Args:
-            file_name: The name of the file to upload.
+            path: The path of the file to upload.
             file_content: The file content as bytes.
 
         Returns:
@@ -75,7 +95,7 @@ class BaseStorageDriver(ABC):
         """
         try:
             # Get signed upload URL
-            upload_response = self.create_signed_upload_url(file_name)
+            upload_response = self.create_signed_upload_url(path)
 
             # Upload the file using the signed URL
             response = httpx.request(
@@ -87,21 +107,21 @@ class BaseStorageDriver(ABC):
             response.raise_for_status()
 
             # Return the download URL
-            return self.create_signed_download_url(file_name)
+            return self.create_signed_download_url(path)
         except httpx.HTTPStatusError as e:
-            msg = f"Failed to upload file {file_name}: {e}"
+            msg = f"Failed to upload file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
         except Exception as e:
-            msg = f"Unexpected error uploading file {file_name}: {e}"
+            msg = f"Unexpected error uploading file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
 
-    def download_file(self, file_name: str) -> bytes:
-        """Download a file from the bucket.
+    def download_file(self, path: Path) -> bytes:
+        """Download a file from storage.
 
         Args:
-            file_name: The name of the file to download.
+            path: The path of the file to download.
 
         Returns:
             The file content as bytes.
@@ -111,17 +131,17 @@ class BaseStorageDriver(ABC):
         """
         try:
             # Get signed download URL
-            download_url = self.create_signed_download_url(file_name)
+            download_url = self.create_signed_download_url(path)
 
             # Download the file
             response = httpx.get(download_url)
             response.raise_for_status()
         except httpx.HTTPStatusError as e:
-            msg = f"Failed to download file {file_name}: {e}"
+            msg = f"Failed to download file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
         except Exception as e:
-            msg = f"Unexpected error downloading file {file_name}: {e}"
+            msg = f"Unexpected error downloading file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
         else:

griptape_nodes/drivers/storage/griptape_cloud_storage_driver.py

@@ -1,5 +1,6 @@
 import logging
 import os
+from pathlib import Path
 from urllib.parse import urljoin
 
 import httpx
@@ -14,52 +15,46 @@ class GriptapeCloudStorageDriver(BaseStorageDriver):
 
     def __init__(
         self,
+        workspace_directory: Path,
         *,
         bucket_id: str,
-        base_url: str | None = None,
         api_key: str | None = None,
-        headers: dict | None = None,
         static_files_directory: str | None = None,
+        **kwargs,
     ) -> None:
         """Initialize the GriptapeCloudStorageDriver.
 
         Args:
+            workspace_directory: The base workspace directory path.
             bucket_id: The ID of the bucket to use. Required.
-            base_url: The base URL for the Griptape Cloud API. If not provided, it will be retrieved from the environment variable "GT_CLOUD_BASE_URL" or default to "https://cloud.griptape.ai".
             api_key: The API key for authentication. If not provided, it will be retrieved from the environment variable "GT_CLOUD_API_KEY".
-            headers: Additional headers to include in the requests. If not provided, the default headers will be used.
             static_files_directory: The directory path prefix for static files. If provided, file names will be prefixed with this path.
+            **kwargs: Additional keyword arguments including base_url and headers.
         """
-        self.base_url = (
-            base_url if base_url is not None else os.environ.get("GT_CLOUD_BASE_URL", "https://cloud.griptape.ai")
-        )
+        super().__init__(workspace_directory)
+
+        self.base_url = kwargs.get("base_url") or os.environ.get("GT_CLOUD_BASE_URL", "https://cloud.griptape.ai")
         self.api_key = api_key if api_key is not None else os.environ.get("GT_CLOUD_API_KEY")
-        self.headers = (
-            headers
-            if headers is not None
-            else {
-                "Authorization": f"Bearer {self.api_key}",
-            }
-        )
+        self.headers = kwargs.get("headers") or {"Authorization": f"Bearer {self.api_key}"}
 
         self.bucket_id = bucket_id
         self.static_files_directory = static_files_directory
 
-    def _get_full_file_path(self, file_name: str) -> str:
-        """Get the full file path including the static files directory prefix.
+    def _get_full_file_path(self, path: Path) -> str:
+        """Get the full file path including workspace directory and static files directory prefix.
 
         Args:
-            file_name: The base file name.
+            path: The relative path from the workspace directory.
 
         Returns:
             The full file path with static files directory prefix if configured.
         """
         if self.static_files_directory:
-            return f"{self.static_files_directory}/{file_name}"
-        return file_name
+            return f"{self.static_files_directory}/{path}"
+        return str(path)
 
-    def create_signed_upload_url(self, file_name: str) -> CreateSignedUploadUrlResponse:
-        full_file_path = self._get_full_file_path(file_name)
+    def create_signed_upload_url(self, path: Path) -> CreateSignedUploadUrlResponse:
+        full_file_path = self._get_full_file_path(path)
         self._create_asset(full_file_path)
 
         url = urljoin(self.base_url, f"/api/buckets/{self.bucket_id}/asset-urls/{full_file_path}")
@@ -67,7 +62,7 @@ class GriptapeCloudStorageDriver(BaseStorageDriver):
             response = httpx.post(url, json={"operation": "PUT"}, headers=self.headers)
             response.raise_for_status()
         except httpx.HTTPStatusError as e:
-            msg = f"Failed to create presigned URL for file {file_name}: {e}"
+            msg = f"Failed to create presigned URL for file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
 
@@ -75,14 +70,14 @@ class GriptapeCloudStorageDriver(BaseStorageDriver):
 
         return {"url": response_data["url"], "headers": response_data.get("headers", {}), "method": "PUT"}
 
-    def create_signed_download_url(self, file_name: str) -> str:
-        full_file_path = self._get_full_file_path(file_name)
+    def create_signed_download_url(self, path: Path) -> str:
+        full_file_path = self._get_full_file_path(path)
         url = urljoin(self.base_url, f"/api/buckets/{self.bucket_id}/asset-urls/{full_file_path}")
         try:
             response = httpx.post(url, json={"method": "GET"}, headers=self.headers)
             response.raise_for_status()
         except httpx.HTTPStatusError as e:
-            msg = f"Failed to create presigned URL for file {file_name}: {e}"
+            msg = f"Failed to create presigned URL for file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
 
@@ -190,19 +185,19 @@ class GriptapeCloudStorageDriver(BaseStorageDriver):
 
         return response.json().get("buckets", [])
 
-    def delete_file(self, file_name: str) -> None:
+    def delete_file(self, path: Path) -> None:
         """Delete a file from the bucket.
 
         Args:
-            file_name: The name of the file to delete.
+            path: The path of the file to delete.
         """
-        full_file_path = self._get_full_file_path(file_name)
+        full_file_path = self._get_full_file_path(path)
         url = urljoin(self.base_url, f"/api/buckets/{self.bucket_id}/assets/{full_file_path}")
 
         try:
             response = httpx.delete(url, headers=self.headers)
             response.raise_for_status()
         except httpx.HTTPStatusError as e:
-            msg = f"Failed to delete file {file_name}: {e}"
+            msg = f"Failed to delete file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e

griptape_nodes/drivers/storage/local_storage_driver.py

@@ -1,5 +1,6 @@
 import logging
 import time
+from pathlib import Path
 from urllib.parse import urljoin
 
 import httpx
@@ -12,13 +13,16 @@ logger = logging.getLogger("griptape_nodes")
 class LocalStorageDriver(BaseStorageDriver):
     """Stores files using the engine's local static server."""
 
-    def __init__(self, base_url: str | None = None) -> None:
+    def __init__(self, workspace_directory: Path, base_url: str | None = None) -> None:
         """Initialize the LocalStorageDriver.
 
         Args:
+            workspace_directory: The base workspace directory path.
             base_url: The base URL for the static file server. If not provided, it will be constructed
         """
-        from griptape_nodes.app.api import (
+        super().__init__(workspace_directory)
+
+        from griptape_nodes.servers.static import (
             STATIC_SERVER_ENABLED,
             STATIC_SERVER_HOST,
             STATIC_SERVER_PORT,
@@ -33,46 +37,46 @@ class LocalStorageDriver(BaseStorageDriver):
         else:
             self.base_url = base_url
 
-    def create_signed_upload_url(self, file_name: str) -> CreateSignedUploadUrlResponse:
+    def create_signed_upload_url(self, path: Path) -> CreateSignedUploadUrlResponse:
         static_url = urljoin(self.base_url, "/static-upload-urls")
         try:
-            response = httpx.post(static_url, json={"file_name": file_name})
+            response = httpx.post(static_url, json={"file_path": str(path)})
             response.raise_for_status()
         except httpx.HTTPStatusError as e:
-            msg = f"Failed to create presigned URL for file {file_name}: {e}"
+            msg = f"Failed to create presigned URL for file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
 
         response_data = response.json()
         url = response_data.get("url")
         if url is None:
-            msg = f"Failed to create presigned URL for file {file_name}: {response_data}"
+            msg = f"Failed to create presigned URL for file {path}: {response_data}"
             logger.error(msg)
             raise ValueError(msg)
 
         return {"url": url, "headers": response_data.get("headers", {}), "method": "PUT"}
 
-    def create_signed_download_url(self, file_name: str) -> str:
-        # The base_url already includes the /static path, so just append the filename
-        url = f"{self.base_url}/{file_name}"
+    def create_signed_download_url(self, path: Path) -> str:
+        # The base_url already includes the /static path, so just append the path
+        url = f"{self.base_url}/{path}"
         # Add a cache-busting query parameter to the URL so that the browser always reloads the file
         cache_busted_url = f"{url}?t={int(time.time())}"
         return cache_busted_url
 
-    def delete_file(self, file_name: str) -> None:
+    def delete_file(self, path: Path) -> None:
         """Delete a file from local storage.
 
         Args:
-            file_name: The name of the file to delete.
+            path: The path of the file to delete.
         """
         # Use the static server's delete endpoint
-        delete_url = urljoin(self.base_url, f"/static-files/{file_name}")
+        delete_url = urljoin(self.base_url, f"/static-files/{path}")
 
         try:
             response = httpx.delete(delete_url)
             response.raise_for_status()
         except httpx.HTTPStatusError as e:
-            msg = f"Failed to delete file {file_name}: {e}"
+            msg = f"Failed to delete file {path}: {e}"
             logger.error(msg)
             raise RuntimeError(msg) from e
 

griptape_nodes/exe_types/node_types.py

@@ -22,6 +22,7 @@ from griptape_nodes.exe_types.core_types import (
     ParameterMode,
     ParameterTypeBuiltin,
 )
+from griptape_nodes.exe_types.param_components.execution_status_component import ExecutionStatusComponent
 from griptape_nodes.exe_types.type_validator import TypeValidator
 from griptape_nodes.retained_mode.events.base_events import (
     ExecutionEvent,
@@ -715,6 +716,9 @@ class BaseNode(ABC):
             raise KeyError(err)
 
     def get_next_control_output(self) -> Parameter | None:
+        # The default behavior for nodes is to find the first control output found.
+        # Advanced nodes can override this behavior (e.g., nodes that have multiple possible
+        # control paths).
         for param in self.parameters:
             if (
                 ParameterTypeBuiltin.CONTROL_TYPE.value == param.output_type
@@ -1150,28 +1154,185 @@ class TrackedParameterOutputValues(dict[str, Any]):
 
 class ControlNode(BaseNode):
     # Control Nodes may have one Control Input Port and at least one Control Output Port
+    def __init__(
+        self,
+        name: str,
+        metadata: dict[Any, Any] | None = None,
+        input_control_name: str | None = None,
+        output_control_name: str | None = None,
+    ) -> None:
+        super().__init__(name, metadata=metadata)
+        self.control_parameter_in = ControlParameterInput(
+            display_name=input_control_name if input_control_name is not None else "Flow In"
+        )
+        self.control_parameter_out = ControlParameterOutput(
+            display_name=output_control_name if output_control_name is not None else "Flow Out"
+        )
+
+        self.add_parameter(self.control_parameter_in)
+        self.add_parameter(self.control_parameter_out)
+
+
+class DataNode(BaseNode):
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
         super().__init__(name, metadata=metadata)
-        control_parameter_in = ControlParameterInput()
-        control_parameter_out = ControlParameterOutput()
 
-        self.add_parameter(control_parameter_in)
-        self.add_parameter(control_parameter_out)
+        # Create control parameters like ControlNode, but initialize them as hidden
+        # This allows the user to turn a DataNode "into" a Control Node; useful when
+        # in situations like within a For Loop.
+        self.control_parameter_in = ControlParameterInput()
+        self.control_parameter_out = ControlParameterOutput()
 
-    def get_next_control_output(self) -> Parameter | None:
-        for param in self.parameters:
-            if (
-                ParameterTypeBuiltin.CONTROL_TYPE.value == param.output_type
-                and ParameterMode.OUTPUT in param.allowed_modes
-            ):
-                return param
-        return None
+        # Hide the control parameters by default
+        self.control_parameter_in.ui_options["hide"] = True
+        self.control_parameter_out.ui_options["hide"] = True
 
+        self.add_parameter(self.control_parameter_in)
+        self.add_parameter(self.control_parameter_out)
+
+
+class SuccessFailureNode(BaseNode):
+    """Base class for nodes that have success/failure branching with control outputs.
+
+    This class provides:
+    - Control input parameter
+    - Two control outputs: success ("exec_out") and failure ("failure")
+    - Execution state tracking for control flow routing
+    - Helper method to check outgoing connections
+    - Helper method to create standard status output parameters
+    """
 
-class DataNode(BaseNode):
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
         super().__init__(name, metadata=metadata)
 
+        # Track execution state for control flow routing
+        self._execution_succeeded: bool | None = None
+
+        # Add control input parameter
+        self.control_parameter_in = ControlParameterInput()
+        self.add_parameter(self.control_parameter_in)
+
+        # Add success control output (uses default "exec_out" name)
+        self.control_parameter_out = ControlParameterOutput(
+            display_name="Succeeded", tooltip="Control path when the operation succeeds"
+        )
+        self.add_parameter(self.control_parameter_out)
+
+        # Add failure control output
+        self.failure_output = ControlParameterOutput(
+            name="failure",
+            display_name="Failed",
+            tooltip="Control path when the operation fails",
+        )
+        self.add_parameter(self.failure_output)
+
+    def get_next_control_output(self) -> Parameter | None:
+        """Determine which control output to follow based on execution result."""
+        if self._execution_succeeded is None:
+            # Execution hasn't completed yet
+            self.stop_flow = True
+            return None
+
+        if self._execution_succeeded:
+            return self.control_parameter_out
+        return self.failure_output
+
+    def _has_outgoing_connections(self, parameter: Parameter) -> bool:
+        """Check if a specific parameter has outgoing connections."""
+        from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+
+        connections = GriptapeNodes.FlowManager().get_connections()
+
+        # Check if node has any outgoing connections
+        node_connections = connections.outgoing_index.get(self.name)
+        if node_connections is None:
+            return False
+
+        # Check if this specific parameter has any outgoing connections
+        param_connections = node_connections.get(parameter.name, [])
+        return len(param_connections) > 0
+
+    def _create_status_parameters(
+        self,
+        result_details_tooltip: str = "Details about the operation result",
+        result_details_placeholder: str = "Details on the operation will be presented here.",
+    ) -> None:
+        """Create and add standard status output parameters in a collapsible group.
+
+        This method creates a "Status" ParameterGroup and immediately adds it to the node.
+        Nodes that use this are responsible for calling this at their desired location
+        in their class constructor.
+
+        Creates and adds:
+        - was_successful: Boolean parameter indicating success/failure
+        - result_details: String parameter with operation details
+
+        Args:
+            result_details_tooltip: Custom tooltip for result_details parameter
+            result_details_placeholder: Custom placeholder text for result_details parameter
+        """
+        # Create status component with OUTPUT modes for SuccessFailureNode
+        self.status_component = ExecutionStatusComponent(
+            self,
+            was_successful_modes={ParameterMode.OUTPUT},
+            result_details_modes={ParameterMode.OUTPUT},
+            parameter_group_initially_collapsed=True,
+            result_details_tooltip=result_details_tooltip,
+            result_details_placeholder=result_details_placeholder,
+        )
+
+    def _clear_execution_status(self) -> None:
+        """Clear execution status and reset status parameters.
+
+        This method should be called at the start of process() to reset the node state.
+        """
+        self._execution_succeeded = None
+        self.status_component.clear_execution_status("Beginning execution...")
+
+    def _set_status_results(self, *, was_successful: bool, result_details: str) -> None:
+        """Set status results and update execution state.
+
+        This method should be called from the process() method to communicate success or failure.
+        It sets the execution state for control flow routing and updates the status output parameters.
+
+        Args:
+            was_successful: Whether the operation succeeded
+            result_details: Details about the operation result
+        """
+        self._execution_succeeded = was_successful
+        self.status_component.set_execution_result(was_successful=was_successful, result_details=result_details)
+
+    def _handle_failure_exception(self, exception: Exception) -> None:
+        """Handle failure exceptions based on whether failure output is connected.
+
+        If the failure output has outgoing connections, logs the error and continues execution
+        to allow graceful failure handling. If no connections exist, raises the exception
+        to crash the flow and provide immediate feedback.
+
+        Args:
+            exception: The exception that caused the failure
+        """
+        if self._has_outgoing_connections(self.failure_output):
+            # User has connected something to Failed output, they want to handle errors gracefully
+            logger.error(
+                "Error in node '%s': %s. Continuing execution since failure output is connected for graceful handling.",
+                self.name,
+                exception,
+            )
+        else:
+            # No graceful handling, raise the exception to crash the flow
+            raise exception
+
+    def validate_before_workflow_run(self) -> list[Exception] | None:
+        """Clear result details before workflow runs to avoid confusion from previous sessions."""
+        self._set_status_results(was_successful=False, result_details="<Results will appear when the node executes>")
+        return super().validate_before_workflow_run()
+
+    def validate_before_node_run(self) -> list[Exception] | None:
+        """Clear result details before node runs to avoid confusion from previous sessions."""
+        self._set_status_results(was_successful=False, result_details="<Results will appear when the node executes>")
+        return super().validate_before_node_run()
+
 
 class StartNode(BaseNode):
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
@@ -1183,7 +1344,51 @@ class EndNode(BaseNode):
     # TODO: https://github.com/griptape-ai/griptape-nodes/issues/854
     def __init__(self, name: str, metadata: dict[Any, Any] | None = None) -> None:
         super().__init__(name, metadata)
-        self.add_parameter(ControlParameterInput())
+
+        # Add dual control inputs
+        self.succeeded_control = ControlParameterInput(
+            display_name="Succeeded", tooltip="Control path when the flow completed successfully"
+        )
+        self.failed_control = ControlParameterInput(
+            name="failed", display_name="Failed", tooltip="Control path when the flow failed"
+        )
+
+        self.add_parameter(self.succeeded_control)
+        self.add_parameter(self.failed_control)
+
+        # Create status component with INPUT and PROPERTY modes
+        self.status_component = ExecutionStatusComponent(
+            self,
+            was_successful_modes={ParameterMode.PROPERTY},
+            result_details_modes={ParameterMode.INPUT},
+            parameter_group_initially_collapsed=False,
+            result_details_placeholder="Details about the completion or failure will be shown here.",
+        )
+
+    def process(self) -> None:
+        # Detect which control input was used to enter this node and determine success status
+        match self._entry_control_parameter:
+            case self.succeeded_control:
+                was_successful = True
+                status_prefix = "[SUCCEEDED]"
+            case self.failed_control:
+                was_successful = False
+                status_prefix = "[FAILED]"
+            case _:
+                # No specific success/failure connection provided, assume success
+                was_successful = True
+                status_prefix = "[SUCCEEDED] No connection provided for success or failure, assuming successful"
+
+        # Get result details and format the final message
+        result_details_value = self.get_parameter_value("result_details")
+        if result_details_value and self._entry_control_parameter in (self.succeeded_control, self.failed_control):
+            details = f"{status_prefix}\n{result_details_value}"
+        elif self._entry_control_parameter in (self.succeeded_control, self.failed_control):
+            details = f"{status_prefix}\nNo details supplied by flow"
+        else:
+            details = status_prefix
+
+        self.status_component.set_execution_result(was_successful=was_successful, result_details=details)
 
 
 class StartLoopNode(BaseNode):

griptape_nodes/exe_types/param_components/__init__.py

@@ -0,0 +1 @@
+"""Parameter components for reusable node functionality."""