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

griptape_nodes/retained_mode/managers/workflow_manager.py

@@ -14,7 +14,6 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple, TypeVar, cast
 
 import aiofiles
-import portalocker
 import semver
 import tomlkit
 from rich.box import HEAVY_EDGE
@@ -59,7 +58,14 @@ from griptape_nodes.retained_mode.events.library_events import (
     ListRegisteredLibrariesRequest,
     ListRegisteredLibrariesResultSuccess,
 )
+from griptape_nodes.retained_mode.events.node_events import CreateNodeGroupRequest
 from griptape_nodes.retained_mode.events.object_events import ClearAllObjectStateRequest
+from griptape_nodes.retained_mode.events.os_events import (
+    ExistingFilePolicy,
+    FileIOFailureReason,
+    WriteFileRequest,
+    WriteFileResultFailure,
+)
 from griptape_nodes.retained_mode.events.workflow_events import (
     BranchWorkflowRequest,
     BranchWorkflowResultFailure,
@@ -70,6 +76,9 @@ from griptape_nodes.retained_mode.events.workflow_events import (
     DeleteWorkflowRequest,
     DeleteWorkflowResultFailure,
     DeleteWorkflowResultSuccess,
+    GetWorkflowMetadataRequest,
+    GetWorkflowMetadataResultFailure,
+    GetWorkflowMetadataResultSuccess,
     ImportWorkflowAsReferencedSubFlowRequest,
     ImportWorkflowAsReferencedSubFlowResultFailure,
     ImportWorkflowAsReferencedSubFlowResultSuccess,
@@ -118,6 +127,9 @@ from griptape_nodes.retained_mode.events.workflow_events import (
     SaveWorkflowRequest,
     SaveWorkflowResultFailure,
     SaveWorkflowResultSuccess,
+    SetWorkflowMetadataRequest,
+    SetWorkflowMetadataResultFailure,
+    SetWorkflowMetadataResultSuccess,
 )
 from griptape_nodes.retained_mode.griptape_nodes import (
     GriptapeNodes,
@@ -332,6 +344,14 @@ class WorkflowManager:
             PublishWorkflowRequest,
             self.on_publish_workflow_request,
         )
+        event_manager.assign_manager_to_request_type(
+            SetWorkflowMetadataRequest,
+            self.on_set_workflow_metadata_request,
+        )
+        event_manager.assign_manager_to_request_type(
+            GetWorkflowMetadataRequest,
+            self.on_get_workflow_metadata_request,
+        )
         event_manager.assign_manager_to_request_type(
             ImportWorkflowAsReferencedSubFlowRequest,
             self.on_import_workflow_as_referenced_sub_flow_request,
@@ -833,10 +853,17 @@ class WorkflowManager:
             details = f"Attempted to rename workflow '{request.workflow_name}' to '{request.requested_name}'. Failed while attempting to save."
             return RenameWorkflowResultFailure(result_details=details)
 
-        delete_workflow_result = await GriptapeNodes.ahandle_request(DeleteWorkflowRequest(name=request.workflow_name))
-        if isinstance(delete_workflow_result, DeleteWorkflowResultFailure):
-            details = f"Attempted to rename workflow '{request.workflow_name}' to '{request.requested_name}'. Failed while attempting to remove the original file name from the registry."
-            return RenameWorkflowResultFailure(result_details=details)
+        # If the original workflow isn't registered, treat this as a Save As and skip deletion
+        if WorkflowRegistry.has_workflow_with_name(request.workflow_name):
+            delete_workflow_result = await GriptapeNodes.ahandle_request(
+                DeleteWorkflowRequest(name=request.workflow_name)
+            )
+            if isinstance(delete_workflow_result, DeleteWorkflowResultFailure):
+                details = (
+                    f"Attempted to rename workflow '{request.workflow_name}' to '{request.requested_name}'. "
+                    "Failed while attempting to remove the original file name from the registry."
+                )
+                return RenameWorkflowResultFailure(result_details=details)
 
         return RenameWorkflowResultSuccess(
             result_details=ResultDetails(
@@ -844,6 +871,96 @@ class WorkflowManager:
             )
         )
 
+    def on_get_workflow_metadata_request(self, request: GetWorkflowMetadataRequest) -> ResultPayload:
+        try:
+            workflow = WorkflowRegistry.get_workflow_by_name(request.workflow_name)
+        except KeyError:
+            details = f"Failed to get metadata. Workflow '{request.workflow_name}' not found."
+            return GetWorkflowMetadataResultFailure(result_details=details)
+
+        return GetWorkflowMetadataResultSuccess(
+            workflow_metadata=workflow.metadata,
+            result_details="Successfully retrieved workflow metadata.",
+        )
+
+    class WorkflowPathResolution(NamedTuple):
+        """Resolution result for workflow and its corresponding file path."""
+
+        workflow: Workflow | None
+        file_path: Path | None
+        error: str | None
+
+    def _get_workflow_and_path(self, workflow_name: str) -> WorkflowPathResolution:
+        """Resolve workflow from registry and return absolute file path."""
+        try:
+            workflow = WorkflowRegistry.get_workflow_by_name(workflow_name)
+        except KeyError:
+            return WorkflowManager.WorkflowPathResolution(
+                workflow=None, file_path=None, error=f"Failed to set metadata. Workflow '{workflow_name}' not found."
+            )
+
+        complete_file_path = WorkflowRegistry.get_complete_file_path(workflow.file_path)
+        file_path_obj = Path(complete_file_path)
+        if not file_path_obj.is_file():
+            return WorkflowManager.WorkflowPathResolution(
+                workflow=workflow,
+                file_path=None,
+                error=f"Failed to set metadata. File path '{complete_file_path}' does not exist.",
+            )
+
+        return WorkflowManager.WorkflowPathResolution(workflow=workflow, file_path=file_path_obj, error=None)
+
+    async def _write_metadata_header(self, file_path: Path, workflow_metadata: WorkflowMetadata) -> str | None:
+        """Replace the workflow header and persist changes to disk."""
+        try:
+            existing_content = file_path.read_text(encoding="utf-8")
+        except OSError as e:
+            return f"Failed to read workflow file '{file_path}': {e!s}"
+
+        updated_content = self._replace_workflow_metadata_header(existing_content, workflow_metadata)
+        if updated_content is None:
+            return "Failed to update metadata header."
+
+        write_result = self._write_workflow_file(
+            file_path=file_path, content=updated_content, file_name=workflow_metadata.name
+        )
+        if not write_result.success:
+            return write_result.error_details
+        return None
+
+    async def on_set_workflow_metadata_request(self, request: SetWorkflowMetadataRequest) -> ResultPayload:
+        await self._workflows_loading_complete.wait()
+
+        # Resolve workflow and file path
+        resolution = self._get_workflow_and_path(request.workflow_name)
+        if resolution.error is not None or resolution.workflow is None or resolution.file_path is None:
+            return SetWorkflowMetadataResultFailure(result_details=resolution.error or "Failed to resolve workflow.")
+
+        # Use provided metadata object as the new metadata
+        new_metadata = request.workflow_metadata
+        # Allow JSON dicts from frontend by coercing to WorkflowMetadata
+        if isinstance(new_metadata, dict):
+            try:
+                new_metadata = WorkflowMetadata.model_validate(new_metadata)
+            except Exception as e:
+                return SetWorkflowMetadataResultFailure(result_details=f"Invalid workflow_metadata: {e!s}")
+        # Refresh last_modified_date to reflect this change
+        new_metadata.last_modified_date = datetime.now(tz=UTC)
+
+        # Persist header
+        write_error = await self._write_metadata_header(file_path=resolution.file_path, workflow_metadata=new_metadata)
+        if write_error is not None:
+            return SetWorkflowMetadataResultFailure(result_details=write_error)
+
+        # Update registry
+        resolution.workflow.metadata = new_metadata
+
+        return SetWorkflowMetadataResultSuccess(
+            result_details=ResultDetails(
+                message=f"Successfully updated metadata for workflow '{request.workflow_name}'.", level=logging.INFO
+            )
+        )
+
     def on_move_workflow_request(self, request: MoveWorkflowRequest) -> ResultPayload:  # noqa: PLR0911
         try:
             # Validate source workflow exists
@@ -1273,7 +1390,7 @@ class WorkflowManager:
     def _write_workflow_file(self, file_path: Path, content: str, file_name: str) -> WriteWorkflowFileResult:
         """Write workflow content to file with proper validation and error handling.
 
-        Uses portalocker for exclusive file locking to prevent concurrent writes.
+        Uses OSManager's WriteFileRequest for file writing with exclusive locking.
         First write wins - if another process is writing, this call fails immediately.
 
         Args:
@@ -1292,41 +1409,36 @@ class WorkflowManager:
             details = f"Attempted to save workflow '{file_name}' (requires {min_space_gb:.1f} GB). Failed due to insufficient disk space: {error_msg}"
             return self.WriteWorkflowFileResult(success=False, error_details=details)
 
-        # Create directory structure
-        try:
-            file_path.parent.mkdir(parents=True, exist_ok=True)
-        except OSError as e:
-            details = f"Attempted to save workflow '{file_name}'. Failed when creating directory structure: {e}"
-            return self.WriteWorkflowFileResult(success=False, error_details=details)
-
-        # Write the file content with exclusive lock (non-blocking)
-        error_details = None
-        try:
-            with portalocker.Lock(
-                file_path,
-                mode="w",
-                encoding="utf-8",
-                timeout=0,  # Non-blocking: fail immediately if locked
-                flags=portalocker.LockFlags.EXCLUSIVE,
-            ) as fh:
-                fh.write(content)
-        except portalocker.LockException:
-            error_details = (
-                f"Attempted to save workflow '{file_name}'. Another process is currently writing to this workflow file"
-            )
-        except PermissionError as e:
-            error_details = f"Attempted to save workflow '{file_name}'. Permission denied: {e}"
-        except IsADirectoryError:
-            error_details = f"Attempted to save workflow '{file_name}'. Path is a directory, not a file"
-        except UnicodeEncodeError as e:
-            error_details = f"Attempted to save workflow '{file_name}'. Content encoding error: {e}"
-        except OSError as e:
-            error_details = f"Attempted to save workflow '{file_name}'. OS error: {e}"
-        except Exception as e:
-            error_details = f"Attempted to save workflow '{file_name}'. Unexpected error: {type(e).__name__}: {e}"
+        # Write file using OSManager's centralized file writing API
+        os_manager = GriptapeNodes.OSManager()
+        write_request = WriteFileRequest(
+            file_path=str(file_path),
+            content=content,
+            encoding="utf-8",
+            append=False,
+            existing_file_policy=ExistingFilePolicy.OVERWRITE,
+            create_parents=True,
+        )
 
-        if error_details:
-            return self.WriteWorkflowFileResult(success=False, error_details=error_details)
+        result = os_manager.on_write_file_request(write_request)
+
+        if isinstance(result, WriteFileResultFailure):
+            # Map failure reasons to workflow-specific error messages
+            match result.failure_reason:
+                case FileIOFailureReason.IO_ERROR:
+                    # Could be lock exception or other I/O error
+                    error_msg = str(result.result_details)
+                case FileIOFailureReason.PERMISSION_DENIED:
+                    error_msg = f"Permission denied: {result.result_details}"
+                case FileIOFailureReason.IS_DIRECTORY:
+                    error_msg = "Path is a directory, not a file"
+                case FileIOFailureReason.ENCODING_ERROR:
+                    error_msg = f"Content encoding error: {result.result_details}"
+                case _:
+                    error_msg = str(result.result_details)
+
+            details = f"Attempted to save workflow '{file_name}'. {error_msg}"
+            return self.WriteWorkflowFileResult(success=False, error_details=details)
 
         return self.WriteWorkflowFileResult(success=True, error_details="")
 
@@ -1336,7 +1448,6 @@ class WorkflowManager:
         current_workflow_name = (
             context_manager.get_current_workflow_name() if context_manager.has_current_workflow() else None
         )
-
         try:
             save_target = self._determine_save_target(
                 requested_file_name=request.file_name,
@@ -1360,70 +1471,68 @@ class WorkflowManager:
             branched_from if branched_from else "None",
         )
 
-        # Serialize the current workflow state
-        top_level_flow_request = GetTopLevelFlowRequest()
-        top_level_flow_result = await GriptapeNodes.ahandle_request(top_level_flow_request)
+        # Serialize current flow and get shape
+        top_level_flow_result = await GriptapeNodes.ahandle_request(GetTopLevelFlowRequest())
         if not isinstance(top_level_flow_result, GetTopLevelFlowResultSuccess):
             details = f"Attempted to save workflow '{relative_file_path}'. Failed when requesting top level flow."
             return SaveWorkflowResultFailure(result_details=details)
-
         top_level_flow_name = top_level_flow_result.flow_name
-        serialized_flow_request = SerializeFlowToCommandsRequest(
-            flow_name=top_level_flow_name, include_create_flow_command=True
+
+        serialized_flow_result = await GriptapeNodes.ahandle_request(
+            SerializeFlowToCommandsRequest(flow_name=top_level_flow_name, include_create_flow_command=True)
         )
-        serialized_flow_result = await GriptapeNodes.ahandle_request(serialized_flow_request)
         if not isinstance(serialized_flow_result, SerializeFlowToCommandsResultSuccess):
             details = f"Attempted to save workflow '{relative_file_path}'. Failed when serializing flow."
             return SaveWorkflowResultFailure(result_details=details)
+        commands = serialized_flow_result.serialized_flow_commands
 
-        serialized_flow_commands = serialized_flow_result.serialized_flow_commands
-
-        # Extract workflow shape if possible
-        workflow_shape = None
+        # Extract workflow shape if available; ignore failures
         try:
             workflow_shape_dict = self.extract_workflow_shape(workflow_name=file_name)
-            workflow_shape = WorkflowShape(inputs=workflow_shape_dict["input"], outputs=workflow_shape_dict["output"])
+            workflow_shape = WorkflowShape(
+                inputs=workflow_shape_dict["input"],
+                outputs=workflow_shape_dict["output"],
+            )
         except ValueError:
-            # If we can't extract workflow shape, continue without it
-            pass
+            workflow_shape = None
+
+        # Build save request inline (preserve existing description/image/is_template if present)
+        existing_description, existing_image, existing_is_template = self._get_existing_metadata(file_name)
 
-        # Use the standalone request to save the workflow file
-        # Use pickle_control_flow_result from request if provided, otherwise use False (default)
-        pickle_control_flow_result = (
-            request.pickle_control_flow_result if request.pickle_control_flow_result is not None else False
-        )
         save_file_request = SaveWorkflowFileFromSerializedFlowRequest(
-            serialized_flow_commands=serialized_flow_commands,
+            serialized_flow_commands=commands,
             file_name=file_name,
             creation_date=creation_date,
-            image_path=request.image_path,
+            image_path=request.image_path if request.image_path is not None else existing_image,
+            description=existing_description,
+            is_template=existing_is_template,
             execution_flow_name=top_level_flow_name,
             branched_from=branched_from,
             workflow_shape=workflow_shape,
             file_path=str(file_path),
-            pickle_control_flow_result=pickle_control_flow_result,
+            pickle_control_flow_result=(
+                request.pickle_control_flow_result if request.pickle_control_flow_result is not None else False
+            ),
         )
-        save_file_result = await self.on_save_workflow_file_from_serialized_flow_request(save_file_request)
 
+        # Execute save and update registry inline
+        save_file_result = await self.on_save_workflow_file_from_serialized_flow_request(save_file_request)
         if not isinstance(save_file_result, SaveWorkflowFileFromSerializedFlowResultSuccess):
-            details = f"Attempted to save workflow '{relative_file_path}'. Failed during file generation: {save_file_result.result_details}"
+            details = (
+                f"Attempted to save workflow '{relative_file_path}'. "
+                f"Failed during file generation: {save_file_result.result_details}"
+            )
             return SaveWorkflowResultFailure(result_details=details)
 
-        # Use the metadata returned by the save operation
         workflow_metadata = save_file_result.workflow_metadata
 
-        # save the created workflow as an entry in the JSON config file.
         registered_workflows = WorkflowRegistry.list_workflows()
         if file_name not in registered_workflows:
-            # Only add to config if it's in the workspace directory (not an external file)
-            if not Path(relative_file_path).is_absolute():
-                try:
-                    GriptapeNodes.ConfigManager().save_user_workflow_json(str(file_path))
-                except OSError as e:
-                    details = f"Attempted to save workflow '{file_name}'. Failed when saving configuration: {e}"
-                    return SaveWorkflowResultFailure(result_details=details)
+            error_details = self._ensure_user_workflow_json_saved(relative_file_path, file_path, file_name)
+            if error_details:
+                return SaveWorkflowResultFailure(result_details=error_details)
             WorkflowRegistry.generate_new_workflow(metadata=workflow_metadata, file_path=relative_file_path)
-        # Update existing workflow's metadata in the registry
+
         existing_workflow = WorkflowRegistry.get_workflow_by_name(file_name)
         existing_workflow.metadata = workflow_metadata
         details = f"Successfully saved workflow to: {save_file_result.file_path}"
@@ -1431,6 +1540,29 @@ class WorkflowManager:
             file_path=save_file_result.file_path, result_details=ResultDetails(message=details, level=logging.INFO)
         )
 
+    def _get_existing_metadata(self, file_name: str) -> tuple[str | None, str | None, bool | None]:
+        """Return (description, image, is_template) for existing workflow if present; otherwise Nones."""
+        if not WorkflowRegistry.has_workflow_with_name(file_name):
+            return None, None, None
+        try:
+            existing = WorkflowRegistry.get_workflow_by_name(file_name)
+        except Exception as err:
+            logger.debug("Preserving existing metadata failed for workflow '%s': %s", file_name, err)
+            return None, None, None
+        else:
+            return existing.metadata.description, existing.metadata.image, existing.metadata.is_template
+
+    def _ensure_user_workflow_json_saved(self, relative_file_path: str, file_path: Path, file_name: str) -> str | None:
+        """Save user workflow JSON when needed; return error details on failure, else None."""
+        if Path(relative_file_path).is_absolute():
+            return None
+        try:
+            GriptapeNodes.ConfigManager().save_user_workflow_json(str(file_path))
+        except OSError as e:
+            return f"Attempted to save workflow '{file_name}'. Failed when saving configuration: {e}"
+        else:
+            return None
+
     def _determine_save_target(
         self, requested_file_name: str | None, current_workflow_name: str | None
     ) -> SaveWorkflowTargetInfo:
@@ -1497,7 +1629,8 @@ class WorkflowManager:
             file_name = requested_file_name
             creation_date = current_workflow.metadata.creation_date
             branched_from = current_workflow.metadata.branched_from
-            relative_file_path = f"{file_name}.py"
+            current_dir = Path(current_workflow.file_path).parent
+            relative_file_path = str(current_dir / f"{file_name}.py")
             file_path = GriptapeNodes.ConfigManager().workspace_path.joinpath(relative_file_path)
 
         else:
@@ -1547,6 +1680,8 @@ class WorkflowManager:
                 file_name=request.file_name,
                 creation_date=creation_date,
                 image_path=request.image_path,
+                description=request.description,
+                is_template=request.is_template,
                 branched_from=request.branched_from,
                 workflow_shape=request.workflow_shape,
             )
@@ -1571,9 +1706,6 @@ class WorkflowManager:
             return SaveWorkflowFileFromSerializedFlowResultFailure(result_details=details)
 
         # Write the workflow file
-        # TODO: https://github.com/griptape-ai/griptape-nodes/issues/3169
-        # This is a synchronous call within an async context and may block the event loop.
-        # Consider using asyncio.to_thread() to run in a thread pool for better async performance.
         write_result = self._write_workflow_file(file_path, final_code_output, request.file_name)
         if not write_result.success:
             return SaveWorkflowFileFromSerializedFlowResultFailure(result_details=write_result.error_details)
@@ -1590,7 +1722,10 @@ class WorkflowManager:
         serialized_flow_commands: SerializedFlowCommands,
         file_name: str,
         creation_date: datetime,
+        *,
         image_path: str | None = None,
+        description: str | None = None,
+        is_template: bool | None = None,
         branched_from: str | None = None,
         workflow_shape: WorkflowShape | None = None,
     ) -> WorkflowMetadata:
@@ -1622,6 +1757,8 @@ class WorkflowManager:
             branched_from=branched_from,
             workflow_shape=workflow_shape,
             image=image_path,
+            description=description,
+            is_template=is_template,
         )
 
     def _generate_workflow_file_content(  # noqa: PLR0912, PLR0915, C901
@@ -1708,15 +1845,33 @@ class WorkflowManager:
                 flow_initialization_command=flow_initialization_command, flow_creation_index=flow_creation_index
             )
 
-            # Generate nodes in flow AST node. This will create the node and apply all element modifiers
-            nodes_in_flow = self._generate_nodes_in_flow(
-                serialized_flow_commands, import_recorder, node_uuid_to_node_variable_name
-            )
+            # Separate regular nodes from NodeGroup nodes in main flow
+            from griptape_nodes.retained_mode.events.node_events import CreateNodeGroupRequest
+
+            regular_node_commands = []
+            node_group_commands = []
+            for serialized_node_command in serialized_flow_commands.serialized_node_commands:
+                create_cmd = serialized_node_command.create_node_command
+                if isinstance(create_cmd, CreateNodeGroupRequest):
+                    node_group_commands.append(serialized_node_command)
+                else:
+                    regular_node_commands.append(serialized_node_command)
 
-            # Add the nodes to the body of the Current Context flow's "with" statement
-            assign_flow_context_node.body.extend(nodes_in_flow)
+            # Track the running node index across all flows to ensure unique variable names
+            current_node_index = 0
 
-            # Process sub-flows - for each sub-flow, generate its initialization command
+            # Generate regular nodes in main flow first (NOT NodeGroups yet)
+            for serialized_node_command in regular_node_commands:
+                node_creation_ast = self._generate_node_creation_code(
+                    serialized_node_command,
+                    current_node_index,
+                    import_recorder,
+                    node_uuid_to_node_variable_name=node_uuid_to_node_variable_name,
+                )
+                assign_flow_context_node.body.extend(node_creation_ast)
+                current_node_index += 1
+
+            # Process sub-flows - for each sub-flow, generate its nodes
             for sub_flow_index, sub_flow_commands in enumerate(serialized_flow_commands.sub_flows_commands):
                 sub_flow_creation_index = flow_creation_index + 1 + sub_flow_index
 
@@ -1726,7 +1881,10 @@ class WorkflowManager:
                     match sub_flow_initialization_command:
                         case CreateFlowRequest():
                             sub_flow_create_node = self._generate_create_flow(
-                                sub_flow_initialization_command, import_recorder, sub_flow_creation_index
+                                sub_flow_initialization_command,
+                                import_recorder,
+                                sub_flow_creation_index,
+                                parent_flow_creation_index=flow_creation_index,
                             )
                             assign_flow_context_node.body.append(cast("ast.stmt", sub_flow_create_node))
                         case ImportWorkflowAsReferencedSubFlowRequest():
@@ -1735,6 +1893,50 @@ class WorkflowManager:
                             )
                             assign_flow_context_node.body.append(cast("ast.stmt", sub_flow_import_node))
 
+                # Generate the nodes in this subflow (just like we do for main flow)
+                if sub_flow_commands.serialized_node_commands:
+                    # Create "with" statement for subflow
+                    subflow_context_node = self._generate_assign_flow_context(
+                        flow_initialization_command=sub_flow_initialization_command,
+                        flow_creation_index=sub_flow_creation_index,
+                    )
+                    # Generate nodes in subflow, passing current index and getting next available
+                    subflow_nodes, current_node_index = self._generate_nodes_in_flow(
+                        sub_flow_commands, import_recorder, node_uuid_to_node_variable_name, current_node_index
+                    )
+                    subflow_context_node.body.extend(subflow_nodes)
+
+                    # Generate connections for nodes in this subflow (must be in subflow context)
+                    subflow_connection_asts = self._generate_connections_code(
+                        serialized_connections=sub_flow_commands.serialized_connections,
+                        node_uuid_to_node_variable_name=node_uuid_to_node_variable_name,
+                        import_recorder=import_recorder,
+                    )
+                    subflow_context_node.body.extend(subflow_connection_asts)
+
+                    # Generate parameter values for nodes in this subflow (must be in subflow context)
+                    subflow_parameter_value_asts = self._generate_set_parameter_value_code(
+                        set_parameter_value_commands=sub_flow_commands.set_parameter_value_commands,
+                        lock_commands=sub_flow_commands.set_lock_commands_per_node,
+                        node_uuid_to_node_variable_name=node_uuid_to_node_variable_name,
+                        unique_values_dict_name="top_level_unique_values_dict",
+                        import_recorder=import_recorder,
+                    )
+                    subflow_context_node.body.extend(subflow_parameter_value_asts)
+
+                    assign_flow_context_node.body.append(subflow_context_node)
+
+            # Generate NodeGroup nodes LAST (after subflows, so child nodes exist)
+            for serialized_node_command in node_group_commands:
+                node_creation_ast = self._generate_node_creation_code(
+                    serialized_node_command,
+                    current_node_index,
+                    import_recorder,
+                    node_uuid_to_node_variable_name=node_uuid_to_node_variable_name,
+                )
+                assign_flow_context_node.body.extend(node_creation_ast)
+                current_node_index += 1
+
             # Now generate the connection code and add it to the flow context
             connection_asts = self._generate_connections_code(
                 serialized_connections=serialized_flow_commands.serialized_connections,
@@ -1743,7 +1945,7 @@ class WorkflowManager:
             )
             assign_flow_context_node.body.extend(connection_asts)
 
-            # Generate parameter values
+            # Generate parameter values for main flow only (subflow parameter values generated inside their contexts)
             set_parameter_value_asts = self._generate_set_parameter_value_code(
                 set_parameter_value_commands=serialized_flow_commands.set_parameter_value_commands,
                 lock_commands=serialized_flow_commands.set_lock_commands_per_node,
@@ -2679,7 +2881,11 @@ class WorkflowManager:
         return full_ast
 
     def _generate_create_flow(
-        self, create_flow_command: CreateFlowRequest, import_recorder: ImportRecorder, flow_creation_index: int
+        self,
+        create_flow_command: CreateFlowRequest,
+        import_recorder: ImportRecorder,
+        flow_creation_index: int,
+        parent_flow_creation_index: int | None = None,
     ) -> ast.Module:
         import_recorder.add_from_import("griptape_nodes.retained_mode.events.flow_events", "CreateFlowRequest")
 
@@ -2691,9 +2897,19 @@ class WorkflowManager:
             for field in fields(create_flow_command):
                 field_value = getattr(create_flow_command, field.name)
                 if field_value != field.default:
-                    create_flow_request_args.append(
-                        ast.keyword(arg=field.name, value=ast.Constant(value=field_value, lineno=1, col_offset=0))
-                    )
+                    # Special handling for parent_flow_name - use variable reference if parent index provided
+                    if field.name == "parent_flow_name" and parent_flow_creation_index is not None:
+                        parent_flow_variable = f"flow{parent_flow_creation_index}_name"
+                        create_flow_request_args.append(
+                            ast.keyword(
+                                arg=field.name,
+                                value=ast.Name(id=parent_flow_variable, ctx=ast.Load(), lineno=1, col_offset=0),
+                            )
+                        )
+                    else:
+                        create_flow_request_args.append(
+                            ast.keyword(arg=field.name, value=ast.Constant(value=field_value, lineno=1, col_offset=0))
+                        )
 
         # Create a comment explaining the behavior
         comment_ast = ast.Expr(
@@ -2904,20 +3120,33 @@ class WorkflowManager:
         serialized_flow_commands: SerializedFlowCommands,
         import_recorder: ImportRecorder,
         node_uuid_to_node_variable_name: dict[SerializedNodeCommands.NodeUUID, str],
-    ) -> list[ast.stmt]:
-        # Generate node creation code and add it to the flow context
+        starting_node_index: int,
+    ) -> tuple[list[ast.stmt], int]:
+        """Generate node creation code for nodes in a flow.
+
+        Args:
+            serialized_flow_commands: Commands for the flow
+            import_recorder: Import recorder for tracking imports
+            node_uuid_to_node_variable_name: Mapping from node UUIDs to variable names
+            starting_node_index: The starting index for node variable names
+
+        Returns:
+            Tuple of (list of AST statements, next available node index)
+        """
         node_creation_asts = []
-        for node_index, serialized_node_command in enumerate(serialized_flow_commands.serialized_node_commands):
+        current_index = starting_node_index
+        for serialized_node_command in serialized_flow_commands.serialized_node_commands:
             node_creation_ast = self._generate_node_creation_code(
                 serialized_node_command,
-                node_index,
+                current_index,
                 import_recorder,
                 node_uuid_to_node_variable_name=node_uuid_to_node_variable_name,
             )
             node_creation_asts.extend(node_creation_ast)
-        return node_creation_asts
+            current_index += 1
+        return node_creation_asts, current_index
 
-    def _generate_node_creation_code(
+    def _generate_node_creation_code(  # noqa: C901, PLR0912
         self,
         serialized_node_command: SerializedNodeCommands,
         node_index: int,
@@ -2951,9 +3180,34 @@ class WorkflowManager:
             for field in fields(create_node_request):
                 field_value = getattr(create_node_request, field.name)
                 if field_value != field.default:
-                    create_node_request_args.append(
-                        ast.keyword(arg=field.name, value=ast.Constant(value=field_value, lineno=1, col_offset=0))
-                    )
+                    # Special handling for CreateNodeGroupRequest.node_names_to_add - these are now UUIDs, convert to variable references
+                    if isinstance(create_node_request, CreateNodeGroupRequest) and field.name == "node_names_to_add":
+                        # field_value is now a list of UUIDs (converted in _serialize_package_nodes_for_local_execution)
+                        # Convert each UUID to an AST Name node referencing the generated variable
+                        node_var_ast_list = []
+                        for node_uuid in field_value:
+                            if node_uuid in node_uuid_to_node_variable_name:
+                                variable_name = node_uuid_to_node_variable_name[node_uuid]
+                                node_var_ast_list.append(ast.Name(id=variable_name, ctx=ast.Load()))
+                            else:
+                                logger.info(
+                                    "NodeGroup child UUID '%s' not found in node_uuid_to_node_variable_name. Available UUIDs: %s...",
+                                    node_uuid,
+                                    list(node_uuid_to_node_variable_name.keys())[:5],
+                                )
+                        if node_var_ast_list:
+                            create_node_request_args.append(
+                                ast.keyword(arg=field.name, value=ast.List(elts=node_var_ast_list, ctx=ast.Load()))
+                            )
+                        else:
+                            logger.info(
+                                "NodeGroup node_names_to_add resulted in empty variable list. Original UUIDs: %s",
+                                field_value,
+                            )
+                    else:
+                        create_node_request_args.append(
+                            ast.keyword(arg=field.name, value=ast.Constant(value=field_value, lineno=1, col_offset=0))
+                        )
         # Get the actual request class name (CreateNodeRequest or CreateNodeGroupRequest)
         request_class_name = type(create_node_request).__name__
         # Handle the create node command and assign to node name
@@ -4158,7 +4412,7 @@ class WorkflowManager:
         failed = []
 
         # First pass: collect all workflow files to determine total count
-        all_workflow_files: list[Path] = []
+        all_workflow_files: set[Path] = set()
 
         def collect_workflow_files(path: Path) -> None:
             """Collect workflow files from a path."""
@@ -4174,7 +4428,7 @@ class WorkflowManager:
                             workflow_file, block_name=WorkflowManager.WORKFLOW_METADATA_HEADER
                         )
                         if len(metadata_blocks) == 1:
-                            all_workflow_files.append(workflow_file)
+                            all_workflow_files.add(workflow_file)
                     except Exception as e:
                         # Skip files that can't be read or parsed
                         logger.debug("Skipping workflow file %s due to error: %s", workflow_file, e)
@@ -4185,7 +4439,7 @@ class WorkflowManager:
                         path, block_name=WorkflowManager.WORKFLOW_METADATA_HEADER
                     )
                     if len(metadata_blocks) == 1:
-                        all_workflow_files.append(path)
+                        all_workflow_files.add(path)
                 except Exception as e:
                     logger.debug("Skipping workflow file %s due to error: %s", path, e)