griptape-nodes 0.64.10__py3-none-any.whl → 0.65.0__py3-none-any.whl

griptape_nodes/retained_mode/events/library_events.py

@@ -181,10 +181,14 @@ class LoadLibraryMetadataFromFileResultSuccess(WorkflowNotAlteredMixin, ResultPa
         library_schema: The validated LibrarySchema object containing all metadata
                        about the library including nodes, categories, and settings.
         file_path: The file path from which the library metadata was loaded.
+        git_remote: The git remote URL if the library is in a git repository, None otherwise.
+        git_ref: The current git reference (branch, tag, or commit) if the library is in a git repository, None otherwise.
     """
 
     library_schema: LibrarySchema
     file_path: str
+    git_remote: str | None
+    git_ref: str | None
 
 
 @dataclass
@@ -539,3 +543,346 @@ class LoadLibrariesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
 @PayloadRegistry.register
 class LoadLibrariesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
     """Library loading failed. Common causes: library loading errors, configuration issues, initialization failures."""
+
+
+@dataclass
+@PayloadRegistry.register
+class CheckLibraryUpdateRequest(RequestPayload):
+    """Check if a library has updates available via git.
+
+    Use when: Checking for library updates, displaying update status,
+    validating library versions, implementing update notifications.
+
+    Args:
+        library_name: Name of the library to check for updates
+
+    Results: CheckLibraryUpdateResultSuccess (with update info) | CheckLibraryUpdateResultFailure (library not found, not a git repo, check error)
+    """
+
+    library_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class CheckLibraryUpdateResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Library update check completed successfully.
+
+    Updates are detected based on either version changes or commit differences:
+    - If remote version > local version: update available (semantic versioning)
+    - If remote version < local version: no update (prevent regression)
+    - If versions equal: compare commits; if different, update available
+
+    Args:
+        has_update: True if an update is available, False otherwise
+        current_version: The current library version
+        latest_version: The latest library version from remote
+        git_remote: The git remote URL
+        git_ref: The current git reference (branch, tag, or commit)
+        local_commit: The local HEAD commit SHA (None if not a git repository)
+        remote_commit: The remote HEAD commit SHA (None if not available)
+    """
+
+    has_update: bool
+    current_version: str | None
+    latest_version: str | None
+    git_remote: str | None
+    git_ref: str | None
+    local_commit: str | None
+    remote_commit: str | None
+
+
+@dataclass
+@PayloadRegistry.register
+class CheckLibraryUpdateResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Library update check failed. Common causes: library not found, not a git repository, git remote error, network error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class UpdateLibraryRequest(RequestPayload):
+    """Update a library to the latest version using the appropriate git strategy.
+
+    Automatically detects whether the library uses branch-based or tag-based workflow:
+    - Branch-based: Uses git fetch + git reset --hard (forces local to match remote)
+    - Tag-based: Uses git fetch --tags --force + git checkout (for moving tags like 'latest')
+
+    Use when: Applying library updates, synchronizing with remote changes,
+    updating library versions, implementing auto-update features.
+
+    Args:
+        library_name: Name of the library to update
+        overwrite_existing: If True, discard any uncommitted local changes. If False, fail if uncommitted changes exist (default: False)
+
+    Results: UpdateLibraryResultSuccess (with version info) | UpdateLibraryResultFailure (library not found, git error, update failure)
+    """
+
+    library_name: str
+    overwrite_existing: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class UpdateLibraryResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Library updated successfully.
+
+    Args:
+        old_version: The previous library version
+        new_version: The new library version after update
+    """
+
+    old_version: str
+    new_version: str
+
+
+@dataclass
+@PayloadRegistry.register
+class UpdateLibraryResultFailure(ResultPayloadFailure):
+    """Library update failed. Common causes: library not found, not a git repository, git pull error, uncommitted changes.
+
+    Args:
+        retryable: If True, the operation can be retried with overwrite_existing=True
+    """
+
+    retryable: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class SwitchLibraryRefRequest(RequestPayload):
+    """Switch a library to a different git branch or tag.
+
+    Supports switching to both branches and tags (e.g., 'main', 'develop', 'latest', 'v1.0.0').
+
+    Use when: Switching between branches for development, testing different versions,
+    reverting to stable branches, checking out feature branches, or switching to specific tags.
+
+    Args:
+        library_name: Name of the library to switch
+        ref_name: Name of the branch or tag to switch to
+
+    Results: SwitchLibraryRefResultSuccess (with ref/version info) | SwitchLibraryRefResultFailure (library not found, git error, ref not found)
+    """
+
+    library_name: str
+    ref_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class SwitchLibraryRefResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Library branch or tag switched successfully.
+
+    Args:
+        old_ref: The previous branch or tag name
+        new_ref: The new branch or tag name after switch
+        old_version: The previous library version
+        new_version: The new library version after switch
+    """
+
+    old_ref: str
+    new_ref: str
+    old_version: str
+    new_version: str
+
+
+@dataclass
+@PayloadRegistry.register
+class SwitchLibraryRefResultFailure(ResultPayloadFailure):
+    """Library ref switch failed. Common causes: library not found, not a git repository, ref not found, git checkout error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class DownloadLibraryRequest(RequestPayload):
+    """Download a library from a git repository.
+
+    Use when: Installing new libraries from git repositories, downloading third-party libraries,
+    setting up development libraries, adding community libraries.
+
+    Args:
+        git_url: The git repository URL to clone
+        branch_tag_commit: Optional branch, tag, or commit to checkout (defaults to default branch)
+        target_directory_name: Optional name for the target directory (defaults to repository name)
+        download_directory: Optional parent directory path for download (defaults to workspace/libraries)
+        overwrite_existing: If True, delete existing directory before cloning (default: False)
+        auto_register: If True, automatically register library after download (default: True)
+        fail_on_exists: If True, fail with retryable error when directory exists and overwrite_existing=False.
+                       If False, skip clone and register existing library (idempotent). (default: True)
+
+    Results: DownloadLibraryResultSuccess (with library info) | DownloadLibraryResultFailure (clone error, directory exists)
+    """
+
+    git_url: str
+    branch_tag_commit: str | None = None
+    target_directory_name: str | None = None
+    download_directory: str | None = None
+    overwrite_existing: bool = False
+    auto_register: bool = True
+    fail_on_exists: bool = True
+
+
+@dataclass
+@PayloadRegistry.register
+class DownloadLibraryResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Library downloaded successfully.
+
+    Args:
+        library_name: Name of the library extracted from griptape_nodes_library.json
+        library_path: Full path where the library was downloaded
+    """
+
+    library_name: str
+    library_path: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DownloadLibraryResultFailure(ResultPayloadFailure):
+    """Library download failed. Common causes: invalid git URL, network error, target directory already exists, no griptape_nodes_library.json found.
+
+    Args:
+        retryable: If True, the operation can be retried with overwrite_existing=True
+    """
+
+    retryable: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class InstallLibraryDependenciesRequest(RequestPayload):
+    """Install dependencies for a library.
+
+    Use when: Installing or reinstalling dependencies for a library,
+    setting up a library's environment, updating dependencies after changes.
+
+    This operation:
+    1. Loads library metadata from the file
+    2. Gets library dependencies from metadata
+    3. Initializes the library's virtual environment
+    4. Installs pip dependencies specified in the library metadata
+    5. Always installs dependencies without version checks
+
+    Args:
+        library_file_path: Path to the library JSON file
+
+    Results: InstallLibraryDependenciesResultSuccess | InstallLibraryDependenciesResultFailure
+    """
+
+    library_file_path: str
+
+
+@dataclass
+@PayloadRegistry.register
+class InstallLibraryDependenciesResultSuccess(ResultPayloadSuccess):
+    """Library dependencies installed successfully.
+
+    Args:
+        library_name: Name of the library whose dependencies were installed
+        dependencies_installed: Number of dependencies that were installed
+    """
+
+    library_name: str
+    dependencies_installed: int
+
+
+@dataclass
+@PayloadRegistry.register
+class InstallLibraryDependenciesResultFailure(ResultPayloadFailure):
+    """Library dependency installation failed. Common causes: library not found, no dependencies defined, venv initialization failed, pip install error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class SyncLibrariesRequest(RequestPayload):
+    """Sync all libraries to latest versions and ensure dependencies are installed.
+
+    Similar to `uv sync` - ensures workspace is in a consistent, up-to-date state.
+    This operation:
+    1. Downloads missing libraries from git URLs specified in config
+    2. Gets all registered libraries (including newly downloaded)
+    3. Checks each library for available updates
+    4. Updates libraries that have updates available
+    5. Installs/updates dependencies for all libraries
+    6. Returns comprehensive summary of changes
+
+    Use when: Updating workspace to latest versions, ensuring all libraries are
+    up-to-date, setting up development environment, periodic maintenance.
+
+    Args:
+        overwrite_existing: If True, discard any uncommitted local changes when updating libraries. If False, fail if uncommitted changes exist (default: False)
+
+    Results: SyncLibrariesResultSuccess (with summary) | SyncLibrariesResultFailure (sync errors)
+    """
+
+    overwrite_existing: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class SyncLibrariesResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Libraries synced successfully.
+
+    Args:
+        libraries_downloaded: Number of libraries that were downloaded from git URLs
+        libraries_checked: Number of libraries checked for updates
+        libraries_updated: Number of libraries that were updated
+        update_summary: Dict mapping library names to their update info (old_version -> new_version, or status for downloads)
+    """
+
+    libraries_downloaded: int
+    libraries_checked: int
+    libraries_updated: int
+    update_summary: dict[str, dict[str, str]]
+
+
+@dataclass
+@PayloadRegistry.register
+class SyncLibrariesResultFailure(ResultPayloadFailure):
+    """Library sync failed. Common causes: git errors, network errors, dependency installation failures."""
+
+
+@dataclass
+@PayloadRegistry.register
+class InspectLibraryRepoRequest(RequestPayload):
+    """Inspect a library's metadata from a git repository without downloading the full repository.
+
+    Performs a sparse checkout to fetch only the library JSON file, which is efficient for
+    previewing library information, checking compatibility, or validating git URLs before
+    full download.
+
+    Use when: Previewing library details, displaying library information in UI,
+    validating library compatibility, checking library versions remotely.
+
+    Args:
+        git_url: Git repository URL (supports GitHub shorthand like "user/repo")
+        ref: Branch, tag, or commit to inspect (defaults to "HEAD")
+
+    Results: InspectLibraryRepoResultSuccess (with library metadata) | InspectLibraryRepoResultFailure (invalid URL, network error, no library JSON found)
+    """
+
+    git_url: str
+    ref: str = "HEAD"
+
+
+@dataclass
+@PayloadRegistry.register
+class InspectLibraryRepoResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Library repository inspection completed successfully.
+
+    Args:
+        library_schema: Complete library schema with all metadata (name, version, nodes, categories, dependencies, settings, etc.)
+        commit_sha: Git commit SHA that was inspected
+        git_url: Git URL that was inspected (normalized)
+        ref: Git reference that was inspected
+    """
+
+    library_schema: LibrarySchema
+    commit_sha: str
+    git_url: str
+    ref: str
+
+
+@dataclass
+@PayloadRegistry.register
+class InspectLibraryRepoResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Library repository inspection failed. Common causes: invalid git URL, network error, no library JSON found, invalid JSON format."""

griptape_nodes/retained_mode/events/node_events.py

@@ -1060,3 +1060,51 @@ class DeleteNodeGroupResultFailure(ResultPayloadFailure):
 
     Common causes: NodeGroup not found, deletion cleanup failed, node is not a NodeGroup.
     """
+
+
+@dataclass
+@PayloadRegistry.register
+class MoveNodeToNewFlowRequest(RequestPayload):
+    """Move a node from one flow to another flow.
+
+    Use when: Reorganizing nodes between flows, adding nodes to NodeGroup subflows,
+    removing nodes from NodeGroup subflows. Node connections are preserved since
+    connections are global and work across flows.
+
+    Args:
+        node_name: Name of the node to move (None for current context)
+        target_flow_name: Name of the destination flow
+        source_flow_name: Name of the source flow (None to use node's current flow)
+
+    Results: MoveNodeToNewFlowResultSuccess | MoveNodeToNewFlowResultFailure (node not found, flow not found, node not in source flow)
+    """
+
+    target_flow_name: str
+    node_name: str | None = None
+    source_flow_name: str | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class MoveNodeToNewFlowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Node moved successfully between flows. Connections preserved.
+
+    Args:
+        node_name: Name of the node that was moved
+        source_flow_name: Name of the flow the node was moved from
+        target_flow_name: Name of the flow the node was moved to
+    """
+
+    node_name: str
+    source_flow_name: str
+    target_flow_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class MoveNodeToNewFlowResultFailure(ResultPayloadFailure):
+    """Node move failed.
+
+    Common causes: node not found, source flow not found, target flow not found,
+    node not in source flow, node is a NodeGroup with subflow conflicts.
+    """

griptape_nodes/retained_mode/events/os_events.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 from dataclasses import dataclass
 from enum import StrEnum
+from typing import TYPE_CHECKING
 
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
@@ -9,6 +12,9 @@ from griptape_nodes.retained_mode.events.base_events import (
 )
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
+if TYPE_CHECKING:
+    from griptape_nodes.retained_mode.events.project_events import MacroPath
+
 
 class ExistingFilePolicy(StrEnum):
     """Policy for handling existing files during write operations."""
@@ -31,6 +37,7 @@ class FileIOFailureReason(StrEnum):
     # Permission/access errors
     PERMISSION_DENIED = "permission_denied"  # No read/write permission
     FILE_NOT_FOUND = "file_not_found"  # File doesn't exist (read operations)
+    FILE_LOCKED = "file_locked"  # File is locked by another process
 
     # Resource errors
     DISK_FULL = "disk_full"  # Insufficient disk space
@@ -38,6 +45,7 @@ class FileIOFailureReason(StrEnum):
     # Path errors
     INVALID_PATH = "invalid_path"  # Malformed or invalid path
     IS_DIRECTORY = "is_directory"  # Path is a directory, not a file
+    MISSING_MACRO_VARIABLES = "missing_macro_variables"  # MacroPath has unresolved required variables
 
     # Content errors
     ENCODING_ERROR = "encoding_error"  # Text encoding/decoding failed
@@ -162,6 +170,8 @@ class ReadFileRequest(RequestPayload):
         workspace_only: If True, constrain to workspace directory. If False, allow system-wide access.
                         If None, workspace constraints don't apply (e.g., cloud environments).
                         TODO: Remove workspace_only parameter - see https://github.com/griptape-ai/griptape-nodes/issues/2753
+        should_transform_image_content_to_thumbnail: If True, convert image files to thumbnail data URLs.
+                        If False, return raw image bytes. Default True for backwards compatibility.
 
     Results: ReadFileResultSuccess (with content) | ReadFileResultFailure (file not found, permission denied)
     """
@@ -170,6 +180,7 @@ class ReadFileRequest(RequestPayload):
     file_entry: FileSystemEntry | None = None
     encoding: str = "utf-8"
     workspace_only: bool | None = True  # TODO: Remove - see https://github.com/griptape-ai/griptape-nodes/issues/2753
+    should_transform_image_content_to_thumbnail: bool = True
 
 
 @dataclass
@@ -310,6 +321,76 @@ class RenameFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
     failure_reason: FileIOFailureReason
 
 
+@dataclass
+@PayloadRegistry.register
+class GetNextUnusedFilenameRequest(RequestPayload):
+    """Find the next available filename with auto-incrementing index (preview only - no file creation).
+
+    Use when: Finding available filenames without file collision before actual write operations.
+
+    This request scans the filesystem and returns the next available filename.
+    This is a preview operation that DOES NOT create any files or acquire any locks.
+
+    Args:
+        file_path: Path to the file (str for direct path, MacroPath for macro resolution)
+
+    Results: GetNextUnusedFilenameResultSuccess | GetNextUnusedFilenameResultFailure
+
+    Examples:
+        # Simple string path - cleanest for most use cases
+        file_path = "/outputs/render.png"
+        # Returns: "/outputs/render.png" if available
+        #          "/outputs/render_1.png" if render.png exists
+        #          "/outputs/render_2.png" if render_1.png exists, etc.
+
+        # MacroPath with required {_index} and padding
+        file_path = MacroPath(
+            parsed_macro=ParsedMacro("{outputs}/frame_{_index:05}.png"),
+            variables={"outputs": "/abs/path"}
+        )
+        # Returns: "/abs/path/frame_00001.png", "/abs/path/frame_00002.png", etc.
+        # Note: Always includes index, cannot return "frame.png"
+
+        # MacroPath with optional {_index} - limited by separator position
+        file_path = MacroPath(
+            parsed_macro=ParsedMacro("{outputs}/frame{_index?:_}.png"),
+            variables={"outputs": "/abs/path"}
+        )
+        # Returns: "/abs/path/frame.png" if {_index} omitted
+        #          "/abs/path/frame1_.png" if {_index}=1 (separator goes after value)
+        # Note: Cannot achieve "frame.png" → "frame_1.png" with optional variable
+    """
+
+    file_path: str | MacroPath
+
+
+@dataclass
+@PayloadRegistry.register
+class GetNextUnusedFilenameResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Next unused filename found (preview only - no file created).
+
+    Attributes:
+        available_filename: Absolute path to the available filename
+        index_used: The index number that was used (e.g., 1, 2, 3...), or None if base filename is available
+    """
+
+    available_filename: str
+    index_used: int | None
+
+
+@dataclass
+@PayloadRegistry.register
+class GetNextUnusedFilenameResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Failed to find available filename.
+
+    Attributes:
+        failure_reason: Classification of why the operation failed
+        result_details: Human-readable error message (inherited from ResultPayloadFailure)
+    """
+
+    failure_reason: FileIOFailureReason
+
+
 @dataclass
 @PayloadRegistry.register
 class WriteFileRequest(RequestPayload):
@@ -321,14 +402,14 @@ class WriteFileRequest(RequestPayload):
     creating configuration files, writing binary data.
 
     Args:
-        file_path: Path to the file to write
+        file_path: Path to the file to write (str for direct path, MacroPath for macro resolution)
         content: Content to write (str for text files, bytes for binary files)
         encoding: Text encoding for str content (default: 'utf-8', ignored for bytes)
         append: If True, append to existing file; if False, use existing_file_policy (default: False)
         existing_file_policy: How to handle existing files when append=False:
             - "overwrite": Replace file content (default)
             - "fail": Return failure if file exists
-            - "create_new": Create new file with modified name (NOT YET IMPLEMENTED)
+            - "create_new": Create new file with auto-incrementing index (e.g., file_1.txt, file_2.txt)
         create_parents: If True, create parent directories if missing (default: True)
 
     Results: WriteFileResultSuccess | WriteFileResultFailure
@@ -336,7 +417,7 @@ class WriteFileRequest(RequestPayload):
     Note: existing_file_policy is ignored when append=True (append always allows existing files)
     """
 
-    file_path: str
+    file_path: str | MacroPath
     content: str | bytes
     encoding: str = "utf-8"  # Ignored for bytes
     append: bool = False
@@ -366,10 +447,12 @@ class WriteFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
 
     Attributes:
         failure_reason: Classification of why the write failed
+        missing_variables: Set of missing variable names (for MISSING_MACRO_VARIABLES failures)
         result_details: Human-readable error message (inherited from ResultPayloadFailure)
     """
 
     failure_reason: FileIOFailureReason
+    missing_variables: set[str] | None = None
 
 
 @dataclass

griptape_nodes/retained_mode/events/project_events.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from enum import StrEnum
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
@@ -25,6 +25,20 @@ if TYPE_CHECKING:
 MacroVariables = dict[str, str | int]
 
 
+class MacroPath(NamedTuple):
+    """A macro path with its parsed template and variable values.
+
+    Used when file paths need macro resolution before filesystem operations.
+
+    Attributes:
+        parsed_macro: The parsed macro template
+        variables: Variable values for macro substitution
+    """
+
+    parsed_macro: ParsedMacro
+    variables: MacroVariables
+
+
 class PathResolutionFailureReason(StrEnum):
     """Reason why path resolution from macro failed."""
 

griptape_nodes/retained_mode/events/workflow_events.py

@@ -632,6 +632,49 @@ class MoveWorkflowResultFailure(ResultPayloadFailure):
     """Workflow move failed. Common causes: workflow not found, invalid target directory, file system error."""
 
 
+@dataclass
+@PayloadRegistry.register
+class GetWorkflowMetadataRequest(RequestPayload):
+    """Get selected metadata for a workflow by name from the registry."""
+
+    workflow_name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class GetWorkflowMetadataResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Workflow metadata retrieved successfully."""
+
+    workflow_metadata: WorkflowMetadata
+
+
+@dataclass
+@PayloadRegistry.register
+class GetWorkflowMetadataResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Workflow metadata retrieval failed. Common causes: workflow not found, registry error, file load error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class SetWorkflowMetadataRequest(RequestPayload):
+    """Replace the workflow's metadata entirely and persist to file."""
+
+    workflow_name: str
+    workflow_metadata: WorkflowMetadata
+
+
+@dataclass
+@PayloadRegistry.register
+class SetWorkflowMetadataResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Workflow metadata updated successfully."""
+
+
+@dataclass
+@PayloadRegistry.register
+class SetWorkflowMetadataResultFailure(ResultPayloadFailure):
+    """Workflow metadata update failed. Common causes: workflow not found, invalid keys/types, file system error."""
+
+
 @dataclass
 @PayloadRegistry.register
 class RegisterWorkflowsFromConfigRequest(RequestPayload):
@@ -681,7 +724,9 @@ class SaveWorkflowFileFromSerializedFlowRequest(RequestPayload):
         serialized_flow_commands: The serialized commands representing the workflow structure
         file_name: Name for the workflow file (without .py extension)
         creation_date: Optional creation date for the workflow metadata (defaults to current time if not provided)
-        image_path: Optional path to workflow image/thumbnail
+        image_path: Optional path to workflow image/thumbnail. If None, callers may preserve existing image.
+        description: Optional workflow description text. If None, callers may preserve existing description.
+        is_template: Optional template status flag. If None, callers may preserve existing template status.
         execution_flow_name: Optional flow name to use for execution code (defaults to file_name if not provided)
         branched_from: Optional branched from information to preserve workflow lineage
         workflow_shape: Optional workflow shape defining inputs and outputs for external callers
@@ -696,6 +741,8 @@ class SaveWorkflowFileFromSerializedFlowRequest(RequestPayload):
     file_path: str | None = None
     creation_date: datetime | None = None
     image_path: str | None = None
+    description: str | None = None
+    is_template: bool | None = None
     execution_flow_name: str | None = None
     branched_from: str | None = None
     workflow_shape: WorkflowShape | None = None