griptape-nodes 0.43.1__py3-none-any.whl → 0.45.0__py3-none-any.whl

griptape_nodes/retained_mode/events/os_events.py

@@ -18,21 +18,23 @@ class FileSystemEntry:
     is_dir: bool
     size: int
     modified_time: float
+    mime_type: str | None = None  # None for directories, mimetype for files
 
 
 @dataclass
 @PayloadRegistry.register
 class OpenAssociatedFileRequest(RequestPayload):
-    """Open a file using the operating system's associated application.
+    """Open a file or directory using the operating system's associated application.
 
     Use when: Opening generated files, launching external applications,
-    providing file viewing capabilities, implementing file associations.
+    providing file viewing capabilities, implementing file associations,
+    opening folders in system explorer.
 
     Args:
-        path_to_file: Path to the file to open (mutually exclusive with file_entry)
+        path_to_file: Path to the file or directory to open (mutually exclusive with file_entry)
         file_entry: FileSystemEntry object from directory listing (mutually exclusive with path_to_file)
 
-    Results: OpenAssociatedFileResultSuccess | OpenAssociatedFileResultFailure (file not found, no association)
+    Results: OpenAssociatedFileResultSuccess | OpenAssociatedFileResultFailure (path not found, no association)
     """
 
     path_to_file: str | None = None
@@ -42,13 +44,13 @@ class OpenAssociatedFileRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class OpenAssociatedFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    """File opened successfully with associated application."""
+    """File or directory opened successfully with associated application."""
 
 
 @dataclass
 @PayloadRegistry.register
 class OpenAssociatedFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    """File opening failed. Common causes: file not found, no associated application, permission denied."""
+    """File or directory opening failed. Common causes: path not found, no associated application, permission denied."""
 
 
 @dataclass
@@ -138,3 +140,93 @@ class ReadFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
 @PayloadRegistry.register
 class ReadFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
     """File reading failed. Common causes: file not found, permission denied, encoding error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class CreateFileRequest(RequestPayload):
+    """Create a new file or directory.
+
+    Use when: Creating files/directories through file picker,
+    implementing file creation functionality.
+
+    Args:
+        path: Path where the file/directory should be created (legacy, use directory_path + name instead)
+        directory_path: Directory where to create the file/directory (mutually exclusive with path)
+        name: Name of the file/directory to create (mutually exclusive with path)
+        is_directory: True to create a directory, False for a file
+        content: Initial content for files (optional)
+        encoding: Text encoding for file content (default: 'utf-8')
+        workspace_only: If True, constrain to workspace directory
+
+    Results: CreateFileResultSuccess | CreateFileResultFailure
+    """
+
+    path: str | None = None
+    directory_path: str | None = None
+    name: str | None = None
+    is_directory: bool = False
+    content: str | None = None
+    encoding: str = "utf-8"
+    workspace_only: bool | None = True
+
+    def get_full_path(self) -> str:
+        """Get the full path, constructing from directory_path + name if path is not provided."""
+        if self.path is not None:
+            return self.path
+        if self.directory_path is not None and self.name is not None:
+            from pathlib import Path
+
+            return str(Path(self.directory_path) / self.name)
+        msg = "Either 'path' or both 'directory_path' and 'name' must be provided"
+        raise ValueError(msg)
+
+
+@dataclass
+@PayloadRegistry.register
+class CreateFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """File/directory created successfully."""
+
+    created_path: str
+
+
+@dataclass
+@PayloadRegistry.register
+class CreateFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """File/directory creation failed."""
+
+
+@dataclass
+@PayloadRegistry.register
+class RenameFileRequest(RequestPayload):
+    """Rename a file or directory.
+
+    Use when: Renaming files/directories through file picker,
+    implementing file rename functionality.
+
+    Args:
+        old_path: Current path of the file/directory to rename
+        new_path: New path for the file/directory
+        workspace_only: If True, constrain to workspace directory
+
+    Results: RenameFileResultSuccess | RenameFileResultFailure
+    """
+
+    old_path: str
+    new_path: str
+    workspace_only: bool | None = True
+
+
+@dataclass
+@PayloadRegistry.register
+class RenameFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """File/directory renamed successfully."""
+
+    old_path: str
+    new_path: str
+
+
+@dataclass
+@PayloadRegistry.register
+class RenameFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """File/directory rename failed."""

griptape_nodes/retained_mode/events/sync_events.py

@@ -0,0 +1,60 @@
+from dataclasses import dataclass
+
+from griptape_nodes.retained_mode.events.base_events import (
+    AppPayload,
+    RequestPayload,
+    ResultPayloadFailure,
+    ResultPayloadSuccess,
+    WorkflowNotAlteredMixin,
+)
+from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
+
+
+@dataclass
+@PayloadRegistry.register
+class StartSyncAllCloudWorkflowsRequest(RequestPayload):
+    """Start syncing all cloud workflows to local synced_workflows directory.
+
+    Use when: Initiating download of all workflow files from cloud storage, keeping local sync directory updated,
+    preparing for offline workflow development, backing up cloud workflows locally.
+
+    Results: StartSyncAllCloudWorkflowsResultSuccess (sync started) | StartSyncAllCloudWorkflowsResultFailure (failed to start)
+    """
+
+
+@dataclass
+@PayloadRegistry.register
+class StartSyncAllCloudWorkflowsResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Cloud workflow sync started successfully.
+
+    Args:
+        sync_directory: Path to the local sync directory where files will be saved
+        total_workflows: Number of workflows that will be synced
+    """
+
+    sync_directory: str
+    total_workflows: int
+
+
+@dataclass
+@PayloadRegistry.register
+class StartSyncAllCloudWorkflowsResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Cloud workflow sync failed to start. Common causes: cloud not configured, network error, storage error, permission denied."""
+
+
+@dataclass
+@PayloadRegistry.register
+class SyncComplete(AppPayload):
+    """Cloud workflow sync completed successfully.
+
+    Args:
+        sync_directory: Path to the local sync directory where files were saved
+        synced_workflows: List of workflows that were successfully synced
+        failed_workflows: List of workflows that failed to sync
+        total_workflows: Total number of workflows that were processed
+    """
+
+    sync_directory: str
+    synced_workflows: list[str]
+    failed_workflows: list[str]
+    total_workflows: int

griptape_nodes/retained_mode/events/workflow_events.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from typing import Literal
 
 from griptape_nodes.node_library.workflow_registry import WorkflowMetadata
 from griptape_nodes.retained_mode.events.base_events import (
@@ -364,3 +365,233 @@ class PublishWorkflowResultSuccess(ResultPayloadSuccess):
 @PayloadRegistry.register
 class PublishWorkflowResultFailure(ResultPayloadFailure):
     """Workflow publish failed. Common causes: workflow not found, publish error, file system error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class BranchWorkflowRequest(RequestPayload):
+    """Create a branch (copy) of an existing workflow with branch tracking.
+
+    Use when: Creating workflow variants, branching workflows for experimentation,
+    creating personal copies of shared workflows, preparing for workflow collaboration.
+
+    Args:
+        workflow_name: Name of the workflow to branch
+        branched_workflow_name: Name for the branched workflow (None for auto-generated)
+
+    Results: BranchWorkflowResultSuccess (with branch name) | BranchWorkflowResultFailure (branch error)
+    """
+
+    workflow_name: str
+    branched_workflow_name: str | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class BranchWorkflowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Workflow branched successfully.
+
+    Args:
+        branched_workflow_name: Name of the created branch
+        original_workflow_name: Name of the original workflow
+    """
+
+    branched_workflow_name: str
+    original_workflow_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class BranchWorkflowResultFailure(ResultPayloadFailure):
+    """Workflow branch failed. Common causes: workflow not found, name conflict, save error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class MergeWorkflowBranchRequest(RequestPayload):
+    """Merge a branch back into its source workflow, removing the branch when complete.
+
+    Use when: Integrating branch changes back into the original workflow, consolidating
+    successful branch experiments, applying approved branch modifications to source.
+
+    Args:
+        workflow_name: Name of the branch workflow to merge back into its source
+
+    Results: MergeWorkflowBranchResultSuccess (with merge details) | MergeWorkflowBranchResultFailure (merge error)
+    """
+
+    workflow_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class MergeWorkflowBranchResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Branch merge back to source completed successfully.
+
+    Args:
+        merged_workflow_name: Name of the source workflow after merge
+    """
+
+    merged_workflow_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class MergeWorkflowBranchResultFailure(ResultPayloadFailure):
+    """Workflow branch merge failed."""
+
+
+@dataclass
+@PayloadRegistry.register
+class ResetWorkflowBranchRequest(RequestPayload):
+    """Reset a branch to match its source workflow, discarding branch changes.
+
+    Use when: Discarding branch modifications, reverting branch to source state,
+    abandoning branch experiments, syncing branch with latest source changes.
+
+    Args:
+        workflow_name: Name of the branch workflow to reset to its source
+
+    Results: ResetWorkflowBranchResultSuccess (with reset details) | ResetWorkflowBranchResultFailure (reset error)
+    """
+
+    workflow_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class ResetWorkflowBranchResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Branch reset to source completed successfully.
+
+    Args:
+        reset_workflow_name: Name of the branch workflow after reset
+    """
+
+    reset_workflow_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class ResetWorkflowBranchResultFailure(ResultPayloadFailure):
+    """Workflow branch reset failed. Common causes: workflows not branch-related, reset conflict, save error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class CompareWorkflowsRequest(RequestPayload):
+    """Compare two workflows to determine if one is ahead, behind, or up-to-date relative to the other.
+
+    Use when: Checking if branched workflows need updates, determining if local changes exist,
+    managing workflow synchronization, preparing for merge operations.
+
+    Args:
+        workflow_name: Name of the workflow to evaluate
+        compare_workflow_name: Name of the workflow to compare against
+
+    Results: CompareWorkflowsResultSuccess (with status details) | CompareWorkflowsResultFailure (evaluation error)
+    """
+
+    workflow_name: str
+    compare_workflow_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class CompareWorkflowsResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Workflow comparison completed successfully.
+
+    Args:
+        workflow_name: Name of the evaluated workflow
+        compare_workflow_name: Name of the workflow being compared against (if any)
+        status: Status relative to source - "up_to_date", "ahead", "behind", "diverged", or "no_source"
+        workflow_last_modified: Last modified timestamp of the workflow
+        source_last_modified: Last modified timestamp of the source (if exists)
+        details: Additional details about the comparison
+    """
+
+    workflow_name: str
+    compare_workflow_name: str | None
+    status: Literal["up_to_date", "ahead", "behind", "diverged", "no_source"]
+    workflow_last_modified: str | None
+    source_last_modified: str | None
+    details: str
+
+
+@dataclass
+@PayloadRegistry.register
+class CompareWorkflowsResultFailure(ResultPayloadFailure):
+    """Workflow comparison failed. Common causes: workflow not found, source not accessible, comparison error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class MoveWorkflowRequest(RequestPayload):
+    """Move a workflow to a different directory in the workspace.
+
+    Use when: Organizing workflows into directories, restructuring workflow hierarchies,
+    moving workflows to categorized folders, cleaning up workspace organization.
+
+    Args:
+        workflow_name: Name of the workflow to move
+        target_directory: Target directory path relative to workspace root
+
+    Results: MoveWorkflowResultSuccess (with new path) | MoveWorkflowResultFailure (move error)
+    """
+
+    workflow_name: str
+    target_directory: str
+
+
+@dataclass
+@PayloadRegistry.register
+class MoveWorkflowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Workflow moved successfully.
+
+    Args:
+        moved_file_path: New file path after the move
+    """
+
+    moved_file_path: str
+
+
+@dataclass
+@PayloadRegistry.register
+class MoveWorkflowResultFailure(ResultPayloadFailure):
+    """Workflow move failed. Common causes: workflow not found, invalid target directory, file system error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class RegisterWorkflowsFromConfigRequest(RequestPayload):
+    """Register workflows from configuration section.
+
+    Use when: Loading workflows from configuration after library initialization,
+    registering workflows from synced directories, batch workflow registration.
+
+    Args:
+        config_section: Configuration section path containing workflow paths to register
+
+    Results: RegisterWorkflowsFromConfigResultSuccess (with count) | RegisterWorkflowsFromConfigResultFailure (registration error)
+    """
+
+    config_section: str
+
+
+@dataclass
+@PayloadRegistry.register
+class RegisterWorkflowsFromConfigResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Workflows registered from configuration successfully.
+
+    Args:
+        succeeded_workflows: List of workflow names that were successfully registered
+        failed_workflows: List of workflow names that failed to register
+    """
+
+    succeeded_workflows: list[str]
+    failed_workflows: list[str]
+
+
+@dataclass
+@PayloadRegistry.register
+class RegisterWorkflowsFromConfigResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Workflow registration from configuration failed. Common causes: configuration not found, invalid paths, registration errors."""

griptape_nodes/retained_mode/griptape_nodes.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import importlib.metadata
 import logging
 import os
 import re
@@ -46,6 +45,7 @@ from griptape_nodes.retained_mode.events.flow_events import (
     DeleteFlowRequest,
 )
 from griptape_nodes.utils.metaclasses import SingletonMeta
+from griptape_nodes.utils.version_utils import engine_version
 
 if TYPE_CHECKING:
     from griptape_nodes.retained_mode.managers.agent_manager import AgentManager
@@ -69,6 +69,7 @@ if TYPE_CHECKING:
     from griptape_nodes.retained_mode.managers.static_files_manager import (
         StaticFilesManager,
     )
+    from griptape_nodes.retained_mode.managers.sync_manager import SyncManager
     from griptape_nodes.retained_mode.managers.version_compatibility_manager import (
         VersionCompatibilityManager,
     )
@@ -78,9 +79,6 @@ if TYPE_CHECKING:
 logger = logging.getLogger("griptape_nodes")
 
 
-engine_version = importlib.metadata.version("griptape_nodes")
-
-
 @dataclass
 class Version:
     major: int
@@ -141,6 +139,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
     _version_compatibility_manager: VersionCompatibilityManager
     _session_manager: SessionManager
     _engine_identity_manager: EngineIdentityManager
+    _sync_manager: SyncManager
 
     def __init__(self) -> None:
         from griptape_nodes.retained_mode.managers.agent_manager import AgentManager
@@ -164,6 +163,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
         from griptape_nodes.retained_mode.managers.static_files_manager import (
             StaticFilesManager,
         )
+        from griptape_nodes.retained_mode.managers.sync_manager import SyncManager
         from griptape_nodes.retained_mode.managers.version_compatibility_manager import (
             VersionCompatibilityManager,
         )
@@ -192,6 +192,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
             self._version_compatibility_manager = VersionCompatibilityManager(self._event_manager)
             self._session_manager = SessionManager(self._event_manager)
             self._engine_identity_manager = EngineIdentityManager(self._event_manager)
+            self._sync_manager = SyncManager(self._event_manager, self._config_manager)
 
             # Assign handlers now that these are created.
             self._event_manager.assign_manager_to_request_type(
@@ -329,6 +330,10 @@ class GriptapeNodes(metaclass=SingletonMeta):
     def EngineIdentityManager(cls) -> EngineIdentityManager:
         return GriptapeNodes.get_instance()._engine_identity_manager
 
+    @classmethod
+    def SyncManager(cls) -> SyncManager:
+        return GriptapeNodes.get_instance()._sync_manager
+
     @classmethod
     def clear_data(cls) -> None:
         # Get canvas

griptape_nodes/retained_mode/managers/config_manager.py

@@ -254,7 +254,7 @@ class ConfigManager:
         existing_workflows = self.get_config_value(config_loc)
         if not existing_workflows:
             existing_workflows = []
-        existing_workflows.append(workflow_file_name)
+        existing_workflows.append(workflow_file_name) if workflow_file_name not in existing_workflows else None
         self.set_config_value(config_loc, existing_workflows)
 
     def delete_user_workflow(self, workflow_file_name: str) -> None:

griptape_nodes/retained_mode/managers/flow_manager.py

@@ -1338,6 +1338,7 @@ class FlowManager:
 
             serialized_node_commands = []
             set_parameter_value_commands_per_node = {}  # Maps a node UUID to a list of set parameter value commands
+            set_lock_commands_per_node = {}  # Maps a node UUID to a set Lock command, if it exists.
 
             # Now each of the child nodes in the flow.
             node_name_to_uuid = {}
@@ -1379,6 +1380,10 @@ class FlowManager:
                     node_libraries_in_use.add(serialized_node.node_library_details)
                     # Get the list of set value commands for THIS node.
                     set_value_commands_list = serialize_node_result.set_parameter_value_commands
+                    if serialize_node_result.serialized_node_commands.lock_node_command is not None:
+                        set_lock_commands_per_node[serialized_node.node_uuid] = (
+                            serialize_node_result.serialized_node_commands.lock_node_command
+                        )
                     set_parameter_value_commands_per_node[serialized_node.node_uuid] = set_value_commands_list
 
             # We'll have to do a patch-up of all the connections, since we can't predict all of the node names being accurate
@@ -1461,6 +1466,7 @@ class FlowManager:
             serialized_connections=create_connection_commands,
             unique_parameter_uuid_to_values=unique_parameter_uuid_to_values,
             set_parameter_value_commands=set_parameter_value_commands_per_node,
+            set_lock_commands_per_node=set_lock_commands_per_node,
             sub_flows_commands=sub_flow_commands,
             node_libraries_used=node_libraries_in_use,
             referenced_workflows=referenced_workflows_in_use,

griptape_nodes/retained_mode/managers/library_manager.py

@@ -13,7 +13,6 @@ from importlib.resources import files
 from pathlib import Path
 from typing import TYPE_CHECKING, cast
 
-import uv
 from packaging.requirements import InvalidRequirement, Requirement
 from pydantic import ValidationError
 from rich.align import Align
@@ -96,6 +95,8 @@ from griptape_nodes.retained_mode.managers.library_lifecycle.library_provenance.
 )
 from griptape_nodes.retained_mode.managers.library_lifecycle.library_status import LibraryStatus
 from griptape_nodes.retained_mode.managers.os_manager import OSManager
+from griptape_nodes.utils.uv_utils import find_uv_bin
+from griptape_nodes.utils.version_utils import get_complete_version_string
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -109,21 +110,6 @@ logger = logging.getLogger("griptape_nodes")
 console = Console()
 
 
-def _find_griptape_uv_bin() -> str:
-    """Find the uv binary, checking dedicated Griptape installation first, then system uv.
-
-    Returns:
-        Path to the uv binary to use
-    """
-    # Check for dedicated Griptape uv installation first
-    dedicated_uv_path = xdg_data_home() / "griptape_nodes" / "bin" / "uv"
-    if dedicated_uv_path.exists():
-        return str(dedicated_uv_path)
-
-    # Fall back to system uv installation
-    return uv.find_uv_bin()
-
-
 class LibraryManager:
     SANDBOX_LIBRARY_NAME = "Sandbox Library"
 
@@ -959,10 +945,12 @@ class LibraryManager:
                     )
                     return RegisterLibraryFromRequirementSpecifierResultFailure()
 
+                uv_path = find_uv_bin()
+
                 logger.info("Installing dependency '%s' with pip in venv at %s", package_name, venv_path)
                 subprocess.run(  # noqa: S603
                     [
-                        _find_griptape_uv_bin(),
+                        uv_path,
                         "pip",
                         "install",
                         request.requirement_specifier,
@@ -1032,9 +1020,10 @@ class LibraryManager:
                 raise RuntimeError(error_message)
 
             try:
+                uv_path = find_uv_bin()
                 logger.info("Creating virtual environment at %s with Python %s", library_venv_path, python_version)
                 subprocess.run(  # noqa: S603
-                    [sys.executable, "-m", "uv", "venv", str(library_venv_path), "--python", python_version],
+                    [uv_path, "venv", str(library_venv_path), "--python", python_version],
                     check=True,
                     capture_output=True,
                     text=True,
@@ -1594,14 +1583,7 @@ class LibraryManager:
         GriptapeNodes.WorkflowManager().on_libraries_initialization_complete()
 
         # Print the engine ready message
-        engine_version_request = GetEngineVersionRequest()
-        engine_version_result = GriptapeNodes.get_instance().handle_engine_version_request(engine_version_request)
-        if isinstance(engine_version_result, GetEngineVersionResultSuccess):
-            engine_version = (
-                f"v{engine_version_result.major}.{engine_version_result.minor}.{engine_version_result.patch}"
-            )
-        else:
-            engine_version = "<UNKNOWN ENGINE VERSION>"
+        engine_version = get_complete_version_string()
 
         # Get current session ID
         session_id = GriptapeNodes.get_session_id()