griptape-nodes 0.41.0__py3-none-any.whl → 0.42.0__py3-none-any.whl

griptape_nodes/retained_mode/events/flow_events.py

@@ -11,32 +11,65 @@ from griptape_nodes.retained_mode.events.base_events import (
 )
 from griptape_nodes.retained_mode.events.node_events import SerializedNodeCommands
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
+from griptape_nodes.retained_mode.events.workflow_events import ImportWorkflowAsReferencedSubFlowRequest
 
 
 @dataclass(kw_only=True)
 @PayloadRegistry.register
 class CreateFlowRequest(RequestPayload):
+    """Create a new flow (sub-workflow) within a parent flow.
+
+    Use when: Creating sub-workflows, organizing complex workflows into components,
+    implementing reusable workflow patterns, building hierarchical workflows.
+
+    Args:
+        parent_flow_name: Name of the parent flow to create the new flow within
+        flow_name: Name for the new flow (None for auto-generated)
+        set_as_new_context: Whether to set this flow as the new current context
+        metadata: Initial metadata for the flow
+
+    Results: CreateFlowResultSuccess (with flow name) | CreateFlowResultFailure (parent not found, name conflicts)
+    """
+
     parent_flow_name: str | None
     flow_name: str | None = None
     # When True, this Flow will be pushed as the new Current Context.
     set_as_new_context: bool = True
+    metadata: dict | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class CreateFlowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Flow created successfully.
+
+    Args:
+        flow_name: Name assigned to the new flow
+    """
+
     flow_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class CreateFlowResultFailure(ResultPayloadFailure):
-    pass
+    """Flow creation failed. Common causes: parent flow not found, name conflicts, invalid parameters."""
 
 
 @dataclass
 @PayloadRegistry.register
 class DeleteFlowRequest(RequestPayload):
+    """Delete a flow and all its contents.
+
+    Use when: Removing unused sub-workflows, cleaning up complex workflows,
+    implementing flow management features. Cascades to delete all nodes and sub-flows.
+
+    Args:
+        flow_name: Name of the flow to delete (None for current context flow)
+
+    Results: DeleteFlowResultSuccess | DeleteFlowResultFailure (flow not found, deletion not allowed)
+    """
+
     # If None is passed, assumes we're deleting the flow in the Current Context.
     flow_name: str | None = None
 
@@ -44,18 +77,29 @@ class DeleteFlowRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class DeleteFlowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Flow deleted successfully. All nodes and sub-flows removed."""
 
 
 @dataclass
 @PayloadRegistry.register
 class DeleteFlowResultFailure(ResultPayloadFailure):
-    pass
+    """Flow deletion failed. Common causes: flow not found, no current context, deletion not allowed."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ListNodesInFlowRequest(RequestPayload):
+    """List all nodes in a specific flow.
+
+    Use when: Inspecting flow contents, building flow visualizations,
+    implementing flow management features, debugging workflow structure.
+
+    Args:
+        flow_name: Name of the flow to list nodes from (None for current context flow)
+
+    Results: ListNodesInFlowResultSuccess (with node names) | ListNodesInFlowResultFailure (flow not found)
+    """
+
     # If None is passed, assumes we're using the flow in the Current Context.
     flow_name: str | None = None
 
@@ -63,13 +107,19 @@ class ListNodesInFlowRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class ListNodesInFlowResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Flow nodes listed successfully.
+
+    Args:
+        node_names: List of node names in the flow
+    """
+
     node_names: list[str]
 
 
 @dataclass
 @PayloadRegistry.register
 class ListNodesInFlowResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Flow nodes listing failed. Common causes: flow not found, no current context."""
 
 
 # We have two different ways to list flows:
@@ -137,8 +187,9 @@ class SerializedFlowCommands:
     Attributes:
         node_libraries_used (set[LibraryNameAndVersion]): Set of libraries and versions used by the nodes,
             including those in child flows.
-        create_flow_command (CreateFlowRequest | None): Command to create the flow that contains all of this.
-            If None, will deserialize into whatever Flow is in the Current Context.
+        flow_initialization_command (CreateFlowRequest | ImportWorkflowAsReferencedSubFlowRequest | None): Command to initialize the flow that contains all of this.
+            Can be CreateFlowRequest for standalone flows, ImportWorkflowAsReferencedSubFlowRequest for referenced workflows,
+            or None to deserialize into whatever Flow is in the Current Context.
         serialized_node_commands (list[SerializedNodeCommands]): List of serialized commands for nodes.
             Handles creating all of the nodes themselves, along with configuring them. Does NOT set Parameter values,
             which is done as a separate step.
@@ -148,6 +199,8 @@ class SerializedFlowCommands:
         set_parameter_value_commands (dict[SerializedNodeCommands.NodeUUID, list[SerializedNodeCommands.IndirectSetParameterValueCommand]]): List of commands
             to set parameter values, keyed by node UUID, during deserialization.
         sub_flows_commands (list["SerializedFlowCommands"]): List of sub-flow commands. Cascades into sub-flows within this serialization.
+        referenced_workflows (set[str]): Set of workflow file paths that are referenced by this flow and its sub-flows.
+            Used for validation before deserialization to ensure all referenced workflows are available.
     """
 
     @dataclass
@@ -169,7 +222,7 @@ class SerializedFlowCommands:
         target_parameter_name: str
 
     node_libraries_used: set[LibraryNameAndVersion]
-    create_flow_command: CreateFlowRequest | None
+    flow_initialization_command: CreateFlowRequest | ImportWorkflowAsReferencedSubFlowRequest | None
     serialized_node_commands: list[SerializedNodeCommands]
     serialized_connections: list[IndirectConnectionSerialization]
     unique_parameter_uuid_to_values: dict[SerializedNodeCommands.UniqueParameterValueUUID, Any]
@@ -177,6 +230,7 @@ class SerializedFlowCommands:
         SerializedNodeCommands.NodeUUID, list[SerializedNodeCommands.IndirectSetParameterValueCommand]
     ]
     sub_flows_commands: list["SerializedFlowCommands"]
+    referenced_workflows: set[str]
 
 
 @dataclass
@@ -223,3 +277,107 @@ class DeserializeFlowFromCommandsResultSuccess(WorkflowAlteredMixin, ResultPaylo
 @PayloadRegistry.register
 class DeserializeFlowFromCommandsResultFailure(ResultPayloadFailure):
     pass
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFlowDetailsRequest(RequestPayload):
+    """Request payload to get detailed information about a flow.
+
+    This provides metadata about a flow including its reference status and parent hierarchy,
+    useful for editor integration to display flows appropriately.
+
+    Attributes:
+        flow_name (str | None): The name of the flow to get details for. If None is passed,
+            assumes we're getting details for the flow in the Current Context.
+    """
+
+    # If None is passed, assumes we're getting details for the flow in the Current Context.
+    flow_name: str | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFlowDetailsResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Success result containing flow details.
+
+    Attributes:
+        referenced_workflow_name (str | None): The name of the workflow that was
+            imported to create this flow. None if this flow was created standalone.
+        parent_flow_name (str | None): The name of the parent flow, or None if this is a
+            top-level flow.
+    """
+
+    referenced_workflow_name: str | None
+    parent_flow_name: str | None
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFlowDetailsResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Failure result when flow details cannot be retrieved.
+
+    This occurs when the specified flow doesn't exist, the current context is empty
+    (when flow_name is None), or there are issues with the flow's parent mapping.
+    """
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFlowMetadataRequest(RequestPayload):
+    """Get metadata associated with a flow.
+
+    Use when: Retrieving flow layout information, getting custom flow properties,
+    implementing flow management features, debugging flow state.
+
+    Results: GetFlowMetadataResultSuccess (with metadata dict) | GetFlowMetadataResultFailure (flow not found)
+    """
+
+    # If None is passed, assumes we're using the Flow in the Current Context
+    flow_name: str | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFlowMetadataResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Flow metadata retrieved successfully.
+
+    Args:
+        metadata: Dictionary containing flow metadata
+    """
+
+    metadata: dict
+
+
+@dataclass
+@PayloadRegistry.register
+class GetFlowMetadataResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Flow metadata retrieval failed. Common causes: flow not found, no current context."""
+
+
+@dataclass
+@PayloadRegistry.register
+class SetFlowMetadataRequest(RequestPayload):
+    """Set metadata associated with a flow.
+
+    Use when: Updating flow layout information, storing custom flow properties,
+    implementing flow management features, saving flow state.
+
+    Results: SetFlowMetadataResultSuccess | SetFlowMetadataResultFailure (flow not found, metadata error)
+    """
+
+    metadata: dict
+    # If None is passed, assumes we're using the Flow in the Current Context
+    flow_name: str | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class SetFlowMetadataResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Flow metadata updated successfully."""
+
+
+@dataclass
+@PayloadRegistry.register
+class SetFlowMetadataResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Flow metadata update failed. Common causes: flow not found, no current context, invalid metadata."""

griptape_nodes/retained_mode/events/library_events.py

@@ -20,42 +20,115 @@ if TYPE_CHECKING:
 @dataclass
 @PayloadRegistry.register
 class ListRegisteredLibrariesRequest(RequestPayload):
-    pass
+    """List all currently registered libraries.
+
+    Use when: Displaying available libraries, checking library availability,
+    building library selection UIs, debugging library registration.
+
+    Results: ListRegisteredLibrariesResultSuccess (with library names) | ListRegisteredLibrariesResultFailure (system error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class ListRegisteredLibrariesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Registered libraries listed successfully.
+
+    Args:
+        libraries: List of registered library names
+    """
+
     libraries: list[str]
 
 
 @dataclass
 @PayloadRegistry.register
 class ListRegisteredLibrariesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Library listing failed. Common causes: registry not initialized, system error."""
+
+
+@dataclass
+@PayloadRegistry.register
+class ListCapableLibraryEventHandlersRequest(RequestPayload):
+    """List libraries capable of handling a specific event type.
+
+    Use when: Finding libraries that can process specific events, implementing event routing,
+    library capability discovery, debugging event handling.
+
+    Results: ListCapableLibraryEventHandlersResultSuccess (with handler names) | ListCapableLibraryEventHandlersResultFailure (query error)
+    """
+
+    request_type: str
+
+
+@dataclass
+@PayloadRegistry.register
+class ListCapableLibraryEventHandlersResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Event handlers listed successfully.
+
+    Args:
+        handlers: List of library names capable of handling the event type
+    """
+
+    handlers: list[str]
+
+
+@dataclass
+@PayloadRegistry.register
+class ListCapableLibraryEventHandlersResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Event handlers listing failed. Common causes: invalid event type, registry error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ListNodeTypesInLibraryRequest(RequestPayload):
+    """List all node types available in a specific library.
+
+    Use when: Discovering available nodes, building node creation UIs,
+    validating node types, exploring library contents.
+
+    Args:
+        library: Name of the library to list node types for
+
+    Results: ListNodeTypesInLibraryResultSuccess (with node types) | ListNodeTypesInLibraryResultFailure (library not found)
+    """
+
     library: str
 
 
 @dataclass
 @PayloadRegistry.register
 class ListNodeTypesInLibraryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Node types in library listed successfully.
+
+    Args:
+        node_types: List of node type names available in the library
+    """
+
     node_types: list[str]
 
 
 @dataclass
 @PayloadRegistry.register
 class ListNodeTypesInLibraryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Node types listing failed. Common causes: library not found, library not loaded."""
 
 
 @dataclass
 @PayloadRegistry.register
 class GetNodeMetadataFromLibraryRequest(RequestPayload):
+    """Get metadata for a specific node type from a library.
+
+    Use when: Inspecting node capabilities, validating node types, building node creation UIs,
+    getting parameter definitions, checking node requirements.
+
+    Args:
+        library: Name of the library containing the node type
+        node_type: Name of the node type to get metadata for
+
+    Results: GetNodeMetadataFromLibraryResultSuccess (with metadata) | GetNodeMetadataFromLibraryResultFailure (node not found)
+    """
+
     library: str
     node_type: str
 
@@ -63,13 +136,19 @@ class GetNodeMetadataFromLibraryRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class GetNodeMetadataFromLibraryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Node metadata retrieved successfully from library.
+
+    Args:
+        metadata: Complete node metadata including parameters, description, requirements
+    """
+
     metadata: NodeMetadata
 
 
 @dataclass
 @PayloadRegistry.register
 class GetNodeMetadataFromLibraryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Node metadata retrieval failed. Common causes: library not found, node type not found, library not loaded."""
 
 
 @dataclass
@@ -179,6 +258,18 @@ class LoadMetadataForAllLibrariesResultFailure(WorkflowNotAlteredMixin, ResultPa
 @dataclass
 @PayloadRegistry.register
 class RegisterLibraryFromFileRequest(RequestPayload):
+    """Register a library from a JSON file.
+
+    Use when: Loading custom libraries, adding new node types,
+    registering development libraries, extending node capabilities.
+
+    Args:
+        file_path: Path to the library JSON file to register
+        load_as_default_library: Whether to load as the default library (default: False)
+
+    Results: RegisterLibraryFromFileResultSuccess (with library name) | RegisterLibraryFromFileResultFailure (load error)
+    """
+
     file_path: str
     load_as_default_library: bool = False
 
@@ -186,18 +277,32 @@ class RegisterLibraryFromFileRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class RegisterLibraryFromFileResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Library registered successfully from file.
+
+    Args:
+        library_name: Name of the registered library
+    """
+
     library_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class RegisterLibraryFromFileResultFailure(ResultPayloadFailure):
-    pass
+    """Library registration from file failed. Common causes: file not found, invalid format, load error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class RegisterLibraryFromRequirementSpecifierRequest(RequestPayload):
+    """Register a library from a requirement specifier (e.g., package name).
+
+    Use when: Installing libraries from package managers, adding dependencies,
+    registering third-party libraries, dynamic library loading.
+
+    Results: RegisterLibraryFromRequirementSpecifierResultSuccess (with library name) | RegisterLibraryFromRequirementSpecifierResultFailure (install error)
+    """
+
     requirement_specifier: str
     library_config_name: str = "griptape_nodes_library.json"
 
@@ -205,61 +310,111 @@ class RegisterLibraryFromRequirementSpecifierRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class RegisterLibraryFromRequirementSpecifierResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Library registered successfully from requirement specifier.
+
+    Args:
+        library_name: Name of the registered library
+    """
+
     library_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class RegisterLibraryFromRequirementSpecifierResultFailure(ResultPayloadFailure):
-    pass
+    """Library registration from requirement specifier failed. Common causes: package not found, installation error, invalid specifier."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ListCategoriesInLibraryRequest(RequestPayload):
+    """List all categories available in a library.
+
+    Use when: Building category-based UIs, organizing node selection,
+    browsing library contents, implementing filters.
+
+    Results: ListCategoriesInLibraryResultSuccess (with categories) | ListCategoriesInLibraryResultFailure (library not found)
+    """
+
     library: str
 
 
 @dataclass
 @PayloadRegistry.register
 class ListCategoriesInLibraryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Library categories listed successfully.
+
+    Args:
+        categories: List of category dictionaries with names, descriptions, and metadata
+    """
+
     categories: list[dict]
 
 
 @dataclass
 @PayloadRegistry.register
 class ListCategoriesInLibraryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Library categories listing failed. Common causes: library not found, library not loaded."""
 
 
 @dataclass
 @PayloadRegistry.register
 class GetLibraryMetadataRequest(RequestPayload):
+    """Get metadata for a specific library.
+
+    Use when: Inspecting library properties, displaying library information,
+    checking library versions, validating library compatibility.
+
+    Results: GetLibraryMetadataResultSuccess (with metadata) | GetLibraryMetadataResultFailure (library not found)
+    """
+
     library: str
 
 
 @dataclass
 @PayloadRegistry.register
 class GetLibraryMetadataResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Library metadata retrieved successfully.
+
+    Args:
+        metadata: Complete library metadata including version, description, dependencies
+    """
+
     metadata: LibraryMetadata
 
 
 @dataclass
 @PayloadRegistry.register
 class GetLibraryMetadataResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Library metadata retrieval failed. Common causes: library not found, library not loaded."""
 
 
 # "Jumbo" event for getting all things say, a GUI might want w/r/t a Library.
 @dataclass
 @PayloadRegistry.register
 class GetAllInfoForLibraryRequest(RequestPayload):
+    """Get comprehensive information for a library in a single call.
+
+    Use when: Populating library UIs, implementing library inspection,
+    gathering complete library state, optimizing multiple info requests.
+
+    Results: GetAllInfoForLibraryResultSuccess (with comprehensive info) | GetAllInfoForLibraryResultFailure (library not found)
+    """
+
     library: str
 
 
 @dataclass
 @PayloadRegistry.register
 class GetAllInfoForLibraryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Comprehensive library information retrieved successfully.
+
+    Args:
+        library_metadata_details: Library metadata and version information
+        category_details: All categories available in the library
+        node_type_name_to_node_metadata_details: Complete node metadata for each node type
+    """
+
     library_metadata_details: GetLibraryMetadataResultSuccess
     category_details: ListCategoriesInLibraryResultSuccess
     node_type_name_to_node_metadata_details: dict[str, GetNodeMetadataFromLibraryResultSuccess]
@@ -268,44 +423,67 @@ class GetAllInfoForLibraryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSu
 @dataclass
 @PayloadRegistry.register
 class GetAllInfoForLibraryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Comprehensive library information retrieval failed. Common causes: library not found, library not loaded, partial failure."""
 
 
 # The "Jumbo-est" of them all. Grabs all info for all libraries in one fell swoop.
 @dataclass
 @PayloadRegistry.register
 class GetAllInfoForAllLibrariesRequest(RequestPayload):
-    pass
+    """Get comprehensive information for all libraries in a single call.
+
+    Use when: Populating complete library catalogs, implementing library browsers,
+    gathering system-wide library state, optimizing bulk library operations.
+
+    Results: GetAllInfoForAllLibrariesResultSuccess (with all library info) | GetAllInfoForAllLibrariesResultFailure (system error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class GetAllInfoForAllLibrariesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Comprehensive information for all libraries retrieved successfully.
+
+    Args:
+        library_name_to_library_info: Complete information for each registered library
+    """
+
     library_name_to_library_info: dict[str, GetAllInfoForLibraryResultSuccess]
 
 
 @dataclass
 @PayloadRegistry.register
 class GetAllInfoForAllLibrariesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Comprehensive information retrieval for all libraries failed. Common causes: registry not initialized, system error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class UnloadLibraryFromRegistryRequest(RequestPayload):
+    """Unload a library from the registry.
+
+    Use when: Removing unused libraries, cleaning up library registry,
+    preparing for library updates, troubleshooting library issues.
+
+    Args:
+        library_name: Name of the library to unload from the registry
+
+    Results: UnloadLibraryFromRegistryResultSuccess | UnloadLibraryFromRegistryResultFailure (library not found, unload error)
+    """
+
     library_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class UnloadLibraryFromRegistryResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Library unloaded successfully from registry."""
 
 
 @dataclass
 @PayloadRegistry.register
 class UnloadLibraryFromRegistryResultFailure(ResultPayloadFailure):
-    pass
+    """Library unload failed. Common causes: library not found, library in use, unload error."""
 
 
 @dataclass
@@ -325,10 +503,10 @@ class ReloadAllLibrariesRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class ReloadAllLibrariesResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """All libraries reloaded successfully. All workflow state has been cleared."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ReloadAllLibrariesResultFailure(ResultPayloadFailure):
-    pass
+    """Library reload failed. Common causes: library loading errors, system constraints, initialization failures."""

griptape_nodes/retained_mode/events/logger_events.py

@@ -9,6 +9,17 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class LogHandlerEvent(AppPayload):
+    """Log message event from the logging system.
+
+    Use when: Capturing log messages for UI display, implementing log viewers,
+    monitoring application behavior, debugging system issues.
+
+    Args:
+        message: The log message content
+        levelname: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        created: Timestamp when the log entry was created
+    """
+
     message: str
     levelname: str
     created: float