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

griptape_nodes/cli/shared.py

@@ -0,0 +1,75 @@
+"""Shared constants and managers for CLI commands."""
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from xdg_base_dirs import xdg_config_home, xdg_data_home
+
+
+@dataclass
+class InitConfig:
+    """Configuration for initialization."""
+
+    interactive: bool = True
+    workspace_directory: str | None = None
+    api_key: str | None = None
+    storage_backend: str | None = None
+    register_advanced_library: bool | None = None
+    config_values: dict[str, Any] | None = None
+    secret_values: dict[str, str] | None = None
+    libraries_sync: bool | None = None
+    bucket_name: str | None = None
+
+
+# Initialize console
+console = Console()
+
+# Directory paths
+CONFIG_DIR = xdg_config_home() / "griptape_nodes"
+DATA_DIR = xdg_data_home() / "griptape_nodes"
+ENV_FILE = CONFIG_DIR / ".env"
+CONFIG_FILE = CONFIG_DIR / "griptape_nodes_config.json"
+
+# URLs and constants
+LATEST_TAG = "latest"
+PACKAGE_NAME = "griptape-nodes"
+NODES_APP_URL = "https://nodes.griptape.ai"
+NODES_TARBALL_URL = "https://github.com/griptape-ai/griptape-nodes/archive/refs/tags/{tag}.tar.gz"
+PYPI_UPDATE_URL = "https://pypi.org/pypi/{package}/json"
+GITHUB_UPDATE_URL = "https://api.github.com/repos/griptape-ai/{package}/git/refs/tags/{revision}"
+GT_CLOUD_BASE_URL = os.getenv("GT_CLOUD_BASE_URL", "https://cloud.griptape.ai")
+
+# Environment variable defaults for init configuration
+ENV_WORKSPACE_DIRECTORY = os.getenv("GTN_WORKSPACE_DIRECTORY")
+ENV_API_KEY = os.getenv("GTN_API_KEY")
+ENV_STORAGE_BACKEND = os.getenv("GTN_STORAGE_BACKEND")
+ENV_REGISTER_ADVANCED_LIBRARY = (
+    os.getenv("GTN_REGISTER_ADVANCED_LIBRARY", "false").lower() == "true"
+    if os.getenv("GTN_REGISTER_ADVANCED_LIBRARY") is not None
+    else None
+)
+ENV_LIBRARIES_SYNC = (
+    os.getenv("GTN_LIBRARIES_SYNC", "false").lower() == "true" if os.getenv("GTN_LIBRARIES_SYNC") is not None else None
+)
+ENV_GTN_BUCKET_NAME = os.getenv("GTN_BUCKET_NAME")
+ENV_LIBRARIES_BASE_DIR = os.getenv("GTN_LIBRARIES_BASE_DIR", str(DATA_DIR / "libraries"))
+
+
+def init_system_config() -> None:
+    """Initializes the system config directory if it doesn't exist."""
+    if not CONFIG_DIR.exists():
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    files_to_create = [
+        (ENV_FILE, ""),
+        (CONFIG_FILE, "{}"),
+    ]
+
+    for file_name in files_to_create:
+        file_path = CONFIG_DIR / file_name[0]
+        if not file_path.exists():
+            with Path.open(file_path, "w", encoding="utf-8") as file:
+                file.write(file_name[1])

griptape_nodes/common/__init__.py

@@ -0,0 +1 @@
+"""Common package."""

griptape_nodes/common/directed_graph.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("griptape_nodes")
+
+
+class DirectedGraph:
+    """Directed graph implementation using Python's graphlib for DAG operations."""
+
+    def __init__(self) -> None:
+        self._nodes: set[str] = set()
+        self._predecessors: dict[str, set[str]] = {}
+
+    def __len__(self) -> int:
+        """Return the number of nodes in the graph."""
+        return len(self._nodes)
+
+    def add_node(self, node_for_adding: str) -> None:
+        """Add a node to the graph."""
+        self._nodes.add(node_for_adding)
+        if node_for_adding not in self._predecessors:
+            self._predecessors[node_for_adding] = set()
+
+    def add_edge(self, from_node: str, to_node: str) -> None:
+        """Add a directed edge from from_node to to_node."""
+        self.add_node(from_node)
+        self.add_node(to_node)
+        self._predecessors[to_node].add(from_node)
+
+    def nodes(self) -> set[str]:
+        """Return all nodes in the graph."""
+        return self._nodes.copy()
+
+    def in_degree(self, node: str) -> int:
+        """Return the in-degree of a node (number of incoming edges)."""
+        if node not in self._nodes:
+            msg = f"Node {node} not found in graph"
+            raise KeyError(msg)
+        return len(self._predecessors.get(node, set()))
+
+    def out_degree(self, node: str) -> int:
+        """Return the out-degree of a node (number of outgoing edges)."""
+        if node not in self._nodes:
+            msg = f"Node {node} not found in graph"
+            raise KeyError(msg)
+        count = 0
+        for predecessors in self._predecessors.values():
+            if node in predecessors:
+                count += 1
+        return count
+
+    def remove_node(self, node: str) -> None:
+        """Remove a node and all its edges from the graph."""
+        if node not in self._nodes:
+            return
+
+        self._nodes.remove(node)
+
+        # Remove this node from all predecessor lists
+        for predecessors in self._predecessors.values():
+            predecessors.discard(node)
+
+        # Remove this node's predecessor entry
+        if node in self._predecessors:
+            del self._predecessors[node]
+
+    def clear(self) -> None:
+        """Clear all nodes and edges from the graph."""
+        self._nodes.clear()
+        self._predecessors.clear()

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,11 +1,10 @@
 import logging
 import time
+from pathlib import Path
 from urllib.parse import urljoin
 
 import httpx
 
-from griptape_nodes.app.api import STATIC_SERVER_HOST, STATIC_SERVER_PORT, STATIC_SERVER_URL
-from griptape_nodes.app.app import STATIC_SERVER_ENABLED
 from griptape_nodes.drivers.storage.base_storage_driver import BaseStorageDriver, CreateSignedUploadUrlResponse
 
 logger = logging.getLogger("griptape_nodes")
@@ -14,12 +13,22 @@ 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
         """
+        super().__init__(workspace_directory)
+
+        from griptape_nodes.servers.static import (
+            STATIC_SERVER_ENABLED,
+            STATIC_SERVER_HOST,
+            STATIC_SERVER_PORT,
+            STATIC_SERVER_URL,
+        )
+
         if not STATIC_SERVER_ENABLED:
             msg = "Static server is not enabled. Please set STATIC_SERVER_ENABLED to True."
             raise ValueError(msg)
@@ -28,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/core_types.py

@@ -4,15 +4,48 @@ import uuid
 from abc import ABC, abstractmethod
 from copy import deepcopy
 from dataclasses import dataclass, field
-from enum import Enum, auto
+from enum import Enum, StrEnum, auto
 from typing import TYPE_CHECKING, Any, ClassVar, Literal, NamedTuple, Self, TypeVar
 
+from pydantic import BaseModel
+
+
+class NodeMessagePayload(BaseModel):
+    """Structured payload for node messages.
+
+    This replaces the use of Any in message payloads, providing
+    better type safety and validation for node message handling.
+    """
+
+    data: Any = None
+
+
+class NodeMessageResult(BaseModel):
+    """Result from a node message callback.
+
+    Attributes:
+        success: True if the message was handled successfully, False otherwise
+        details: Human-readable description of what happened
+        response: Optional response data to return to the sender
+        altered_workflow_state: True if the message handling altered workflow state.
+            Clients can use this to determine if the workflow needs to be re-saved.
+    """
+
+    success: bool
+    details: str
+    response: NodeMessagePayload | None = None
+    altered_workflow_state: bool = True
+
+
 if TYPE_CHECKING:
     from collections.abc import Callable
     from types import TracebackType
 
     from griptape_nodes.exe_types.node_types import BaseNode
 
+# Type alias for element message callback functions
+type ElementMessageCallback = Callable[[str, "NodeMessagePayload | None"], "NodeMessageResult"]
+
 T = TypeVar("T", bound="Parameter")
 N = TypeVar("N", bound="BaseNodeElement")
 
@@ -24,7 +57,7 @@ class ParameterMode(Enum):
     PROPERTY = auto()
 
 
-class ParameterTypeBuiltin(Enum):
+class ParameterTypeBuiltin(StrEnum):
     STR = "str"
     BOOL = "bool"
     INT = "int"
@@ -416,6 +449,31 @@ class BaseNodeElement:
         }
         return event_data
 
+    def on_message_received(self, message_type: str, message: NodeMessagePayload | None) -> NodeMessageResult | None:
+        """Virtual method for handling messages sent to this element.
+
+        Attempts to delegate to child elements first. If any child handles the message
+        (returns non-None), that result is returned immediately. Otherwise, falls back
+        to default behavior (return None).
+
+        Args:
+            message_type: String indicating the message type for parsing
+            message: Message payload as NodeMessagePayload or None
+
+        Returns:
+            NodeMessageResult | None: Result if handled, None if no handler available
+        """
+        # Try to delegate to all children first
+        # NOTE: This returns immediately on the first child that accepts the message (returns non-None).
+        # In the future, we may need to expand this to handle multiple children processing the same message.
+        for child in self._children:
+            result = child.on_message_received(message_type, message)
+            if result is not None:
+                return result
+
+        # No child handled it, return None (indicating no handler)
+        return None
+
 
 class UIOptionsMixin:
     """Mixin providing UI options update functionality for classes with ui_options."""