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

griptape_nodes/cli/commands/libraries.py

@@ -0,0 +1,90 @@
+"""Libraries command for Griptape Nodes CLI."""
+
+import asyncio
+import shutil
+import tarfile
+import tempfile
+from pathlib import Path
+
+import httpx
+import typer
+from rich.progress import Progress
+
+from griptape_nodes.cli.shared import (
+    ENV_LIBRARIES_BASE_DIR,
+    LATEST_TAG,
+    NODES_TARBALL_URL,
+    console,
+)
+from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+from griptape_nodes.utils.version_utils import get_current_version, get_install_source
+
+app = typer.Typer(help="Manage local libraries.")
+
+
+@app.command()
+def sync() -> None:
+    """Sync libraries with your current engine version."""
+    asyncio.run(_sync_libraries())
+
+
+async def _sync_libraries() -> None:
+    """Download and sync Griptape Nodes libraries, copying only directories from synced libraries."""
+    install_source, _ = get_install_source()
+    # Unless we're installed from PyPi, grab libraries from the 'latest' tag
+    if install_source == "pypi":
+        version = get_current_version()
+    else:
+        version = LATEST_TAG
+
+    console.print(f"[bold cyan]Fetching Griptape Nodes libraries ({version})...[/bold cyan]")
+
+    tar_url = NODES_TARBALL_URL.format(tag=version)
+    console.print(f"[green]Downloading from {tar_url}[/green]")
+    dest_nodes = Path(ENV_LIBRARIES_BASE_DIR)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tar_path = Path(tmp) / "nodes.tar.gz"
+
+        # Streaming download with a tiny progress bar
+        with httpx.stream("GET", tar_url, follow_redirects=True) as r, Progress() as progress:
+            task = progress.add_task("[green]Downloading...", total=int(r.headers.get("Content-Length", 0)))
+            progress.start()
+            try:
+                r.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                console.print(f"[red]Error fetching libraries: {e}[/red]")
+                return
+            with tar_path.open("wb") as f:
+                for chunk in r.iter_bytes():
+                    f.write(chunk)
+                    progress.update(task, advance=len(chunk))
+
+        console.print("[green]Extracting...[/green]")
+        # Extract and locate extracted directory
+        with tarfile.open(tar_path) as tar:
+            tar.extractall(tmp, filter="data")
+
+        extracted_root = next(Path(tmp).glob("griptape-nodes-*"))
+        extracted_libs = extracted_root / "libraries"
+
+        # Copy directories from synced libraries without removing existing content
+        console.print(f"[green]Syncing libraries to {dest_nodes.resolve()}...[/green]")
+        dest_nodes.mkdir(parents=True, exist_ok=True)
+        for library_dir in extracted_libs.iterdir():
+            if library_dir.is_dir():
+                dest_library_dir = dest_nodes / library_dir.name
+                if dest_library_dir.exists():
+                    shutil.rmtree(dest_library_dir)
+                shutil.copytree(library_dir, dest_library_dir)
+                console.print(f"[green]Synced library: {library_dir.name}[/green]")
+
+    # Re-initialize all libraries from config
+    console.print("[bold cyan]Initializing libraries...[/bold cyan]")
+    try:
+        await GriptapeNodes.LibraryManager().load_all_libraries_from_config()
+        console.print("[bold green]Libraries Initialized successfully.[/bold green]")
+    except Exception as e:
+        console.print(f"[red]Error initializing libraries: {e}[/red]")
+
+    console.print("[bold green]Libraries synced.[/bold green]")

griptape_nodes/cli/commands/self.py

@@ -0,0 +1,117 @@
+"""Self command for Griptape Nodes CLI."""
+
+import shutil
+import sys
+
+import typer
+
+from griptape_nodes.cli.shared import (
+    CONFIG_DIR,
+    DATA_DIR,
+    GITHUB_UPDATE_URL,
+    LATEST_TAG,
+    PYPI_UPDATE_URL,
+    config_manager,
+    console,
+    os_manager,
+)
+from griptape_nodes.utils.uv_utils import find_uv_bin
+from griptape_nodes.utils.version_utils import (
+    get_complete_version_string,
+    get_current_version,
+    get_latest_version_git,
+    get_latest_version_pypi,
+)
+
+app = typer.Typer(help="Manage this CLI installation.")
+
+
+@app.command()
+def update() -> None:
+    """Update the CLI."""
+    _update_self()
+
+
+@app.command()
+def uninstall() -> None:
+    """Uninstall the CLI."""
+    _uninstall_self()
+
+
+@app.command()
+def version() -> None:
+    """Print the CLI version."""
+    _print_current_version()
+
+
+def _get_latest_version(package: str, install_source: str) -> str:
+    """Fetches the latest release tag from PyPI.
+
+    Args:
+        package: The name of the package to fetch the latest version for.
+        install_source: The source from which the package is installed (e.g., "pypi", "git", "file").
+
+    Returns:
+        str: Latest release tag (e.g., "v0.31.4")
+    """
+    if install_source == "pypi":
+        return get_latest_version_pypi(package, PYPI_UPDATE_URL)
+    if install_source == "git":
+        return get_latest_version_git(package, GITHUB_UPDATE_URL, LATEST_TAG)
+    # If the package is installed from a file, just return the current version since the user is likely managing it manually
+    return get_current_version()
+
+
+def _update_self() -> None:
+    """Installs the latest release of the CLI *and* refreshes bundled libraries."""
+    console.print("[bold green]Starting updater...[/bold green]")
+
+    os_manager.replace_process([sys.executable, "-m", "griptape_nodes.updater"])
+
+
+def _print_current_version() -> None:
+    """Prints the current version of the script."""
+    version_string = get_complete_version_string()
+    console.print(f"[bold green]{version_string}[/bold green]")
+
+
+def _uninstall_self() -> None:
+    """Uninstalls itself by removing config/data directories and the executable."""
+    console.print("[bold]Uninstalling Griptape Nodes...[/bold]")
+
+    # Remove config and data directories
+    console.print("[bold]Removing config and data directories...[/bold]")
+    dirs = [(CONFIG_DIR, "Config Dir"), (DATA_DIR, "Data Dir")]
+    caveats = []
+    for dir_path, dir_name in dirs:
+        if dir_path.exists():
+            console.print(f"[bold]Removing {dir_name} '{dir_path}'...[/bold]")
+            try:
+                shutil.rmtree(dir_path)
+            except OSError as exc:
+                console.print(f"[red]Error removing {dir_name} '{dir_path}': {exc}[/red]")
+                caveats.append(
+                    f"- [red]Error removing {dir_name} '{dir_path}'. You may want remove this directory manually.[/red]"
+                )
+        else:
+            console.print(f"[yellow]{dir_name} '{dir_path}' does not exist; skipping.[/yellow]")
+
+    # Handle any remaining config files not removed by design
+    remaining_config_files = config_manager.config_files
+    if remaining_config_files:
+        caveats.append("- Some config files were intentionally not removed:")
+        caveats.extend(f"\t[yellow]- {file}[/yellow]" for file in remaining_config_files)
+
+    # If there were any caveats to the uninstallation process, print them
+    if caveats:
+        console.print("[bold]Caveats:[/bold]")
+        for line in caveats:
+            console.print(line)
+
+    # Remove the executable
+    console.print("[bold]Removing the executable...[/bold]")
+    console.print("[bold yellow]When done, press Enter to exit.[/bold yellow]")
+
+    # Remove the tool using UV
+    uv_path = find_uv_bin()
+    os_manager.replace_process([uv_path, "tool", "uninstall", "griptape-nodes"])

griptape_nodes/cli/main.py

@@ -0,0 +1,46 @@
+"""Main CLI application using typer."""
+
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+# Add current directory to path for imports to work
+sys.path.append(str(Path.cwd()))
+
+from griptape_nodes.cli.commands import config, engine, init, libraries, self
+
+console = Console()
+
+app = typer.Typer(
+    name="griptape-nodes",
+    help="Griptape Nodes Engine CLI",
+    no_args_is_help=False,
+    rich_markup_mode="rich",
+    invoke_without_command=True,
+)
+
+# Add subcommands
+app.command("init", help="Initialize engine configuration.")(init.init_command)
+app.add_typer(config.app, name="config")
+app.add_typer(self.app, name="self")
+app.add_typer(libraries.app, name="libraries")
+app.command("engine")(engine.engine_command)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    no_update: bool = typer.Option(  # noqa: FBT001
+        False, "--no-update", help="Skip the auto-update check."
+    ),
+) -> None:
+    """Griptape Nodes Engine CLI."""
+    if ctx.invoked_subcommand is None:
+        # Default to engine command when no subcommand is specified
+        engine.engine_command(no_update=no_update)
+
+
+if __name__ == "__main__":
+    app()

griptape_nodes/cli/shared.py

@@ -0,0 +1,84 @@
+"""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
+
+from griptape_nodes.retained_mode.managers.config_manager import ConfigManager
+from griptape_nodes.retained_mode.managers.os_manager import OSManager
+from griptape_nodes.retained_mode.managers.secrets_manager import SecretsManager
+
+
+@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"))
+
+# Initialize managers
+config_manager = ConfigManager()
+secrets_manager = SecretsManager(config_manager)
+os_manager = OSManager()
+
+
+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,55 @@
+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 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:
+            return 0
+        return len(self._predecessors.get(node, set()))
+
+    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/local_storage_driver.py

@@ -4,8 +4,6 @@ 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")
@@ -20,6 +18,13 @@ class LocalStorageDriver(BaseStorageDriver):
         Args:
             base_url: The base URL for the static file server. If not provided, it will be constructed
         """
+        from griptape_nodes.app.api 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)

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."""

griptape_nodes/exe_types/node_types.py

@@ -6,12 +6,13 @@ from abc import ABC, abstractmethod
 from collections.abc import Callable, Generator, Iterable
 from concurrent.futures import ThreadPoolExecutor
 from enum import StrEnum, auto
-from typing import Any, NamedTuple, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from griptape_nodes.exe_types.core_types import (
     BaseNodeElement,
     ControlParameterInput,
     ControlParameterOutput,
+    NodeMessageResult,
     Parameter,
     ParameterContainer,
     ParameterDictionary,
@@ -39,6 +40,9 @@ from griptape_nodes.retained_mode.events.parameter_events import (
 )
 from griptape_nodes.traits.options import Options
 
+if TYPE_CHECKING:
+    from griptape_nodes.exe_types.core_types import NodeMessagePayload
+
 logger = logging.getLogger("griptape_nodes")
 
 T = TypeVar("T")
@@ -54,23 +58,6 @@ class NodeResolutionState(StrEnum):
     RESOLVED = auto()
 
 
-class NodeMessageResult(NamedTuple):
-    """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: Any = None
-    altered_workflow_state: bool = True
-
-
 class BaseNode(ABC):
     # Owned by a flow
     name: str
@@ -80,7 +67,7 @@ class BaseNode(ABC):
     state: NodeResolutionState
     current_spotlight_parameter: Parameter | None = None
     parameter_values: dict[str, Any]
-    parameter_output_values: dict[str, Any]
+    parameter_output_values: TrackedParameterOutputValues
     stop_flow: bool = False
     root_ui_element: BaseNodeElement
     _tracked_parameters: list[BaseNodeElement]
@@ -289,15 +276,18 @@ class BaseNode(ABC):
 
     def on_node_message_received(
         self,
-        optional_element_name: str | None,  # noqa: ARG002
+        optional_element_name: str | None,
         message_type: str,
-        message: Any,  # noqa: ARG002
+        message: NodeMessagePayload | None,
     ) -> NodeMessageResult:
         """Callback for when a message is sent directly to this node.
 
         Custom nodes may elect to override this method to handle specific message types
         and implement custom communication patterns with external systems.
 
+        If optional_element_name is provided, this method will attempt to find the
+        element and delegate the message handling to that element's on_message_received method.
+
         Args:
             optional_element_name: Optional element name this message relates to
             message_type: String indicating the message type for parsing
@@ -306,6 +296,26 @@ class BaseNode(ABC):
         Returns:
             NodeMessageResult: Result containing success status, details, and optional response
         """
+        # If optional_element_name is provided, delegate to the specific element
+        if optional_element_name is not None:
+            element = self.root_ui_element.find_element_by_name(optional_element_name)
+            if element is None:
+                return NodeMessageResult(
+                    success=False,
+                    details=f"Node '{self.name}' received message for element '{optional_element_name}' but no element with that name was found",
+                    response=None,
+                )
+            # Delegate to the element's message handler
+            result = element.on_message_received(message_type, message)
+            if result is None:
+                return NodeMessageResult(
+                    success=False,
+                    details=f"Element '{optional_element_name}' received message type '{message_type}' but no handler was available",
+                    response=None,
+                )
+            return result
+
+        # If no element name specified, fall back to node-level handling
         return NodeMessageResult(
             success=False,
             details=f"Node '{self.name}' was sent a message of type '{message_type}'. Failed because no message handler was specified for this node. Implement the on_node_message_received method in this node class in order for it to receive messages.",
@@ -620,10 +630,10 @@ class BaseNode(ABC):
         # Allow custom node logic to prepare and possibly mutate the value before it is actually set.
         # Record any parameters modified for cascading.
         if not initial_setup:
-            if not skip_before_value_set:
-                final_value = self.before_value_set(parameter=parameter, value=candidate_value)
-            else:
+            if skip_before_value_set:
                 final_value = candidate_value
+            else:
+                final_value = self.before_value_set(parameter=parameter, value=candidate_value)
             # ACTUALLY SET THE NEW VALUE
             self.parameter_values[param_name] = final_value
 
@@ -1097,6 +1107,10 @@ class TrackedParameterOutputValues(dict[str, Any]):
             for key in keys_to_clear:
                 self._emit_parameter_change_event(key, None, deleted=True)
 
+    def silent_clear(self) -> None:
+        """Clear all values without emitting parameter change events."""
+        super().clear()
+
     def update(self, *args, **kwargs) -> None:
         # Handle both dict.update(other) and dict.update(**kwargs) patterns
         if args: