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

griptape_nodes/retained_mode/events/node_events.py

@@ -31,6 +31,24 @@ class NewPosition(NamedTuple):
 @dataclass
 @PayloadRegistry.register
 class CreateNodeRequest(RequestPayload):
+    """Create a new node in a workflow.
+
+    Use when: Building workflows programmatically, responding to user requests ("add a CSV reader"),
+    loading saved workflows. Validates node type exists, generates unique name if needed.
+
+    Args:
+        node_type: Class name of the node to create
+        specific_library_name: Library to search for the node type (None for any library)
+        node_name: Desired name for the node (None for auto-generated)
+        override_parent_flow_name: Flow to create the node in (None for current context)
+        metadata: Initial metadata for the node (position, display properties)
+        resolution: Initial resolution state (defaults to UNRESOLVED)
+        initial_setup: Skip setup work when loading from file (defaults to False)
+        set_as_new_context: Set this node as current context after creation (defaults to False)
+
+    Results: CreateNodeResultSuccess (with assigned name) | CreateNodeResultFailure (invalid type, missing library, flow not found)
+    """
+
     node_type: str
     specific_library_name: str | None = None
     node_name: str | None = None
@@ -47,6 +65,14 @@ class CreateNodeRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class CreateNodeResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Node created successfully. Node is now available for parameter setting, connections, and execution.
+
+    Args:
+        node_name: Final assigned name (may differ from requested)
+        node_type: Class name of created node
+        specific_library_name: Library that provided this node type
+    """
+
     node_name: str
     node_type: str
     specific_library_name: str | None = None
@@ -55,12 +81,27 @@ class CreateNodeResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class CreateNodeResultFailure(ResultPayloadFailure):
-    pass
+    """Node creation failed.
+
+    Common causes: invalid node_type, missing library, flow not found,
+    no current context, or instantiation errors. Workflow unchanged.
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class DeleteNodeRequest(RequestPayload):
+    """Delete a node from a workflow.
+
+    Use when: Removing obsolete nodes, cleaning up failed nodes, restructuring workflows,
+    implementing undo. Handles cascading cleanup of connections and execution cancellation.
+
+    Args:
+        node_name: Name of the node to delete (None for current context node)
+
+    Results: DeleteNodeResultSuccess | DeleteNodeResultFailure (node not found, cleanup failed)
+    """
+
     # If None is passed, assumes we're using the Node in the Current Context.
     node_name: str | None = None
 
@@ -68,18 +109,33 @@ class DeleteNodeRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class DeleteNodeResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Node deleted successfully. Node and all connections removed, no longer available for use."""
 
 
 @dataclass
 @PayloadRegistry.register
 class DeleteNodeResultFailure(ResultPayloadFailure):
-    pass
+    """Node deletion failed.
+
+    Common causes: node not found, no current context,
+    execution cancellation failed, or connection cleanup failed. Workflow unchanged.
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class GetNodeResolutionStateRequest(RequestPayload):
+    """Get the current resolution state of a node.
+
+    Use when: Checking if node is ready to execute, monitoring execution progress,
+    workflow orchestration, debugging. States: UNRESOLVED -> RESOLVED -> EXECUTING -> COMPLETED/FAILED
+
+    Args:
+        node_name: Name of the node to check (None for current context node)
+
+    Results: GetNodeResolutionStateResultSuccess (with state) | GetNodeResolutionStateResultFailure (node not found)
+    """
+
     # If None is passed, assumes we're using the Node in the Current Context
     node_name: str | None = None
 
@@ -87,18 +143,35 @@ class GetNodeResolutionStateRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class GetNodeResolutionStateResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Node resolution state retrieved successfully.
+
+    Args:
+        state: Current state (UNRESOLVED, RESOLVED, EXECUTING, COMPLETED, FAILED)
+    """
+
     state: str
 
 
 @dataclass
 @PayloadRegistry.register
 class GetNodeResolutionStateResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Resolution state retrieval failed. Common causes: node not found, no current context."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ListParametersOnNodeRequest(RequestPayload):
+    """List all parameter names available on a node.
+
+    Use when: Parameter discovery, validation before setting values, generating UIs,
+    implementing completion features. Names can be used with GetParameterValue, SetParameterValue, connections.
+
+    Args:
+        node_name: Name of the node to list parameters for (None for current context node)
+
+    Results: ListParametersOnNodeResultSuccess (with parameter names) | ListParametersOnNodeResultFailure (node not found)
+    """
+
     # If None is passed, assumes we're using the Node in the Current Context
     node_name: str | None = None
 
@@ -106,18 +179,35 @@ class ListParametersOnNodeRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class ListParametersOnNodeResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Parameter names retrieved successfully.
+
+    Args:
+        parameter_names: List of parameter names available on the node
+    """
+
     parameter_names: list[str]
 
 
 @dataclass
 @PayloadRegistry.register
 class ListParametersOnNodeResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Parameter listing failed. Common causes: node not found, no current context."""
 
 
 @dataclass
 @PayloadRegistry.register
 class GetNodeMetadataRequest(RequestPayload):
+    """Retrieve metadata associated with a node.
+
+    Use when: Getting node position for layout, retrieving custom properties, implementing selection,
+    saving/loading workflow layout. Metadata doesn't affect execution but provides workflow context.
+
+    Args:
+        node_name: Name of the node to get metadata for (None for current context node)
+
+    Results: GetNodeMetadataResultSuccess (with metadata dict) | GetNodeMetadataResultFailure (node not found)
+    """
+
     # If None is passed, assumes we're using the Node in the Current Context
     node_name: str | None = None
 
@@ -125,18 +215,36 @@ class GetNodeMetadataRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class GetNodeMetadataResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Node metadata retrieved successfully.
+
+    Args:
+        metadata: Dictionary containing position, display properties, custom user data
+    """
+
     metadata: dict
 
 
 @dataclass
 @PayloadRegistry.register
 class GetNodeMetadataResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Metadata retrieval failed. Common causes: node not found, no current context."""
 
 
 @dataclass
 @PayloadRegistry.register
 class SetNodeMetadataRequest(RequestPayload):
+    """Update metadata associated with a node.
+
+    Use when: Updating node position, storing custom properties/annotations, implementing styling,
+    saving user preferences. Metadata doesn't affect execution but provides workflow context.
+
+    Args:
+        metadata: Dictionary of metadata to set (position, display properties, custom data)
+        node_name: Name of the node to update metadata for (None for current context node)
+
+    Results: SetNodeMetadataResultSuccess | SetNodeMetadataResultFailure (node not found, update error)
+    """
+
     metadata: dict
     # If None is passed, assumes we're using the Node in the Current Context
     node_name: str | None = None
@@ -145,13 +253,13 @@ class SetNodeMetadataRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class SetNodeMetadataResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Node metadata updated successfully. New metadata stored and available for future requests."""
 
 
 @dataclass
 @PayloadRegistry.register
 class SetNodeMetadataResultFailure(ResultPayloadFailure):
-    pass
+    """Metadata update failed. Common causes: node not found, no current context, invalid metadata format."""
 
 
 # Get all info via a "jumbo" node event. Batches multiple info requests for, say, a GUI.
@@ -159,6 +267,17 @@ class SetNodeMetadataResultFailure(ResultPayloadFailure):
 @dataclass
 @PayloadRegistry.register
 class GetAllNodeInfoRequest(RequestPayload):
+    """Retrieve comprehensive information about a node in a single call.
+
+    Use when: Populating UIs, implementing node inspection/debugging, gathering complete state
+    for serialization, optimizing performance. Batches metadata, resolution state, connections, parameters.
+
+    Args:
+        node_name: Name of the node to get information for (None for current context node)
+
+    Results: GetAllNodeInfoResultSuccess (with comprehensive info) | GetAllNodeInfoResultFailure (node not found)
+    """
+
     # If None is passed, assumes we're using the Node in the Current Context
     node_name: str | None = None
 
@@ -172,6 +291,16 @@ class ParameterInfoValue:
 @dataclass
 @PayloadRegistry.register
 class GetAllNodeInfoResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Comprehensive node information retrieved successfully.
+
+    Args:
+        metadata: Node metadata (position, display properties, etc.)
+        node_resolution_state: Current execution state
+        connections: All incoming and outgoing connections
+        element_id_to_value: Parameter details and values by element ID
+        root_node_element: Root element information
+    """
+
     metadata: dict
     node_resolution_state: str
     connections: ListConnectionsForNodeResultSuccess
@@ -182,7 +311,10 @@ class GetAllNodeInfoResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess)
 @dataclass
 @PayloadRegistry.register
 class GetAllNodeInfoResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Comprehensive node information retrieval failed.
+
+    Common causes: node not found, no current context, partial failure in gathering information components.
+    """
 
 
 # A Node's state can be serialized to a sequence of commands that the engine runs.
@@ -278,16 +410,17 @@ class SerializedParameterValueTracker:
 @dataclass
 @PayloadRegistry.register
 class SerializeNodeToCommandsRequest(RequestPayload):
-    """Request payload to serialize a node into a sequence of commands.
+    """Serialize a node into a sequence of commands.
 
-    Attributes:
-        node_name (str | None): The name of the node to serialize. If None, the node in the current context is used.
-        unique_parameter_uuid_to_values (dict[SerializedNodeCommands.UniqueParameterValueUUID, Any]): Mapping of
-            UUIDs to unique parameter values. Serialization will check a parameter's value against these, inserting
-            new values if necessary. NOTE that it modifies the dict in-place.
-        serialized_parameter_value_tracker (SerializedParameterValueTracker): Mapping of hash values to unique parameter
-            value UUIDs. If serialization adds new unique values, they are added to this map. Unserializable values
-            are preserved to prevent duplicate serialization attempts.
+    Use when: Implementing copy/paste, exporting nodes, creating templates, backing up nodes.
+    Captures complete node state including parameters and connections.
+
+    Args:
+        node_name: Name of the node to serialize (None for current context node)
+        unique_parameter_uuid_to_values: Mapping of UUIDs to unique parameter values (modified in-place)
+        serialized_parameter_value_tracker: Tracks serialization state of parameter values
+
+    Results: SerializeNodeToCommandsResultSuccess (with commands) | SerializeNodeToCommandsResultFailure (serialization error)
     """
 
     node_name: str | None = None
@@ -350,6 +483,17 @@ class SerializedSelectedNodesCommands:
 @dataclass
 @PayloadRegistry.register
 class SerializeSelectedNodesToCommandsRequest(WorkflowNotAlteredMixin, RequestPayload):
+    """Serialize multiple selected nodes into commands.
+
+    Use when: Implementing copy/paste, exporting workflow sections, creating templates,
+    backing up workflows, transferring configurations. Preserves nodes and interconnections.
+
+    Args:
+        nodes_to_serialize: List of node identifiers (each containing [node_name, timestamp])
+
+    Results: SerializeSelectedNodesToCommandsResultSuccess (with commands) | SerializeSelectedNodesToCommandsResultFailure (node not found, serialization error)
+    """
+
     # They will be passed with node_name, timestamp
     nodes_to_serialize: list[list[str]]
 
@@ -357,6 +501,14 @@ class SerializeSelectedNodesToCommandsRequest(WorkflowNotAlteredMixin, RequestPa
 @dataclass
 @PayloadRegistry.register
 class SerializeSelectedNodesToCommandsResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Selected nodes serialized successfully.
+
+    Preserves complete structure including node configurations, parameter values, and connection relationships.
+
+    Args:
+        serialized_selected_node_commands: Complete serialized representation
+    """
+
     # They will be passed with node_name, timestamp
     # Could be a flow command if it's all nodes in a flow.
     serialized_selected_node_commands: SerializedSelectedNodesCommands
@@ -365,58 +517,127 @@ class SerializeSelectedNodesToCommandsResultSuccess(WorkflowNotAlteredMixin, Res
 @dataclass
 @PayloadRegistry.register
 class SerializeSelectedNodesToCommandsResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Selected nodes serialization failed.
+
+    Common causes: nodes not found, non-serializable parameter values, connection resolution failures.
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class DeserializeSelectedNodesFromCommandsRequest(WorkflowNotAlteredMixin, RequestPayload):
+    """Recreate nodes from serialized commands.
+
+    Use when: Implementing paste functionality, importing configurations, restoring from backups,
+    duplicating complex structures. Creates new nodes with unique names and restores parameters/connections.
+
+    Args:
+        positions: List of positions for the recreated nodes (None for default positions)
+
+    Results: DeserializeSelectedNodesFromCommandsResultSuccess (with node names) | DeserializeSelectedNodesFromCommandsResultFailure (deserialization error)
+    """
+
     positions: list[NewPosition] | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class DeserializeSelectedNodesFromCommandsResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Nodes recreated successfully from serialized commands. Parameter values and connections restored.
+
+    Args:
+        node_names: List of names assigned to newly created nodes
+    """
+
     node_names: list[str]
 
 
 @dataclass
 @PayloadRegistry.register
 class DeserializeSelectedNodesFromCommandsResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Nodes recreation failed.
+
+    Common causes: invalid/corrupted commands, missing node types/libraries,
+    parameter deserialization failures, connection creation errors.
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class DeserializeNodeFromCommandsRequest(RequestPayload):
+    """Recreate a single node from serialized commands.
+
+    Use when: Restoring individual nodes from backups/templates, implementing node-level copy/paste,
+    loading configurations, creating from templates. Creates new node with unique name and restores parameters.
+
+    Args:
+        serialized_node_commands: Serialized node commands containing complete node state
+
+    Results: DeserializeNodeFromCommandsResultSuccess (with node name) | DeserializeNodeFromCommandsResultFailure (deserialization error)
+    """
+
     serialized_node_commands: SerializedNodeCommands
 
 
 @dataclass
 @PayloadRegistry.register
 class DeserializeNodeFromCommandsResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Node recreated successfully from serialized commands. Parameter values restored.
+
+    Args:
+        node_name: Name assigned to newly created node
+    """
+
     node_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class DeserializeNodeFromCommandsResultFailure(ResultPayloadFailure):
-    pass
+    """Node recreation failed.
+
+    Common causes: invalid/corrupted commands, missing node type/library,
+    parameter deserialization failures, creation errors or constraints.
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class DuplicateSelectedNodesRequest(WorkflowNotAlteredMixin, RequestPayload):
+    """Duplicate selected nodes with new positions.
+
+    Use when: Implementing duplicate functionality, creating multiple instances of same configuration,
+    expanding workflows by replicating patterns, quick copying without serialization overhead.
+    Preserves connections between duplicated nodes.
+
+    Args:
+        nodes_to_duplicate: List of node identifiers to duplicate (each containing [node_name, timestamp])
+        positions: List of positions for the duplicated nodes (None for default positions)
+
+    Results: DuplicateSelectedNodesResultSuccess (with node names) | DuplicateSelectedNodesResultFailure (duplication error)
+    """
+
     nodes_to_duplicate: list[list[str]]
+    positions: list[NewPosition] | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class DuplicateSelectedNodesResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Nodes duplicated successfully. Configuration and connections preserved.
+
+    Args:
+        node_names: List of names assigned to newly duplicated nodes
+    """
+
     node_names: list[str]
 
 
 @dataclass
 @PayloadRegistry.register
 class DuplicateSelectedNodesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Node duplication failed.
+
+    Common causes: nodes not found, constraints/conflicts,
+    insufficient resources, connection duplication failures.
+    """

griptape_nodes/retained_mode/events/object_events.py

@@ -12,6 +12,19 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class RenameObjectRequest(RequestPayload):
+    """Rename an object (node, flow, etc.) in the system.
+
+    Use when: Organizing workflows, fixing naming conflicts, implementing rename features,
+    improving readability. Can automatically find alternative names if requested name is taken.
+
+    Args:
+        object_name: Current name of the object to rename
+        requested_name: New name for the object
+        allow_next_closest_name_available: Whether to use alternative name if requested name is taken
+
+    Results: RenameObjectResultSuccess (with final name) | RenameObjectResultFailure (rename failed)
+    """
+
     object_name: str
     requested_name: str
     allow_next_closest_name_available: bool = False
@@ -20,28 +33,51 @@ class RenameObjectRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class RenameObjectResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """Object renamed successfully.
+
+    Args:
+        final_name: The actual name assigned (may differ from requested if auto-naming was used)
+    """
+
     final_name: str  # May not be the same as what was requested, if that bool was set
 
 
 @dataclass
 @PayloadRegistry.register
 class RenameObjectResultFailure(ResultPayloadFailure):
+    """Object rename failed.
+
+    Args:
+        next_available_name: Suggested alternative name (None if not available)
+    """
+
     next_available_name: str | None
 
 
-# This request will wipe all Flows, Nodes, Connections, everything.
-# But you knew that, right? You knew what you were doing when you called it?
 @dataclass
 @PayloadRegistry.register
 class ClearAllObjectStateRequest(RequestPayload):
+    """WARNING: Clear all object state - wipes all flows, nodes, connections, everything!
+
+    Use when: Resetting to clean state, recovering from corruption, starting fresh,
+    implementing reset functionality. Requires explicit confirmation.
+
+    Args:
+        i_know_what_im_doing: Confirmation flag that must be set to True to proceed
+
+    Results: ClearAllObjectStateResultSuccess | ClearAllObjectStateResultFailure (clear failed)
+    """
+
     i_know_what_im_doing: bool = False
 
 
+@dataclass
 @PayloadRegistry.register
 class ClearAllObjectStateResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """All object state cleared successfully. System is now in clean state."""
 
 
+@dataclass
 @PayloadRegistry.register
 class ClearAllObjectStateResultFailure(ResultPayloadFailure):
-    pass
+    """Object state clearing failed. Common causes: confirmation not provided, clear operation failed."""

griptape_nodes/retained_mode/events/os_events.py

@@ -12,16 +12,27 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class OpenAssociatedFileRequest(RequestPayload):
+    """Open a file using the operating system's associated application.
+
+    Use when: Opening generated files, launching external applications,
+    providing file viewing capabilities, implementing file associations.
+
+    Args:
+        path_to_file: Path to the file to open with the associated application
+
+    Results: OpenAssociatedFileResultSuccess | OpenAssociatedFileResultFailure (file not found, no association)
+    """
+
     path_to_file: str
 
 
 @dataclass
 @PayloadRegistry.register
 class OpenAssociatedFileResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
-    pass
+    """File opened successfully with associated application."""
 
 
 @dataclass
 @PayloadRegistry.register
 class OpenAssociatedFileResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """File opening failed. Common causes: file not found, no associated application, permission denied."""