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

griptape_nodes/retained_mode/events/config_events.py

@@ -13,24 +13,53 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class GetConfigValueRequest(RequestPayload):
+    """Get a specific configuration value.
+
+    Use when: Reading application settings, checking node configurations, retrieving user preferences,
+    accessing environment-specific values. Key format: "category.key" or "category.subcategory.key".
+
+    Args:
+        category_and_key: Configuration key in format "category.key" or "category.subcategory.key"
+
+    Results: GetConfigValueResultSuccess (with value) | GetConfigValueResultFailure (key not found)
+    """
+
     category_and_key: str
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConfigValueResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Configuration value retrieved successfully.
+
+    Args:
+        value: The configuration value (can be any type)
+    """
+
     value: Any
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConfigValueResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Configuration value retrieval failed. Common causes: key not found, invalid category format."""
 
 
 @dataclass
 @PayloadRegistry.register
 class SetConfigValueRequest(RequestPayload):
+    """Set a specific configuration value.
+
+    Use when: Updating application settings, configuring node behavior, storing user preferences,
+    setting environment-specific values. Key format: "category.key" or "category.subcategory.key".
+
+    Args:
+        category_and_key: Configuration key in format "category.key" or "category.subcategory.key"
+        value: Value to set for the configuration key
+
+    Results: SetConfigValueResultSuccess | SetConfigValueResultFailure (invalid key, value error)
+    """
+
     category_and_key: str
     value: Any
 
@@ -38,36 +67,65 @@ class SetConfigValueRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class SetConfigValueResultSuccess(ResultPayloadSuccess):
-    pass
+    """Configuration value set successfully."""
 
 
 @dataclass
 @PayloadRegistry.register
 class SetConfigValueResultFailure(ResultPayloadFailure):
-    pass
+    """Configuration value setting failed. Common causes: invalid key format, value validation error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConfigCategoryRequest(RequestPayload):
+    """Get all configuration values within a category.
+
+    Use when: Retrieving multiple related settings, displaying configuration sections in UIs,
+    backing up/restoring configuration groups, bulk configuration operations.
+
+    Args:
+        category: Name of the configuration category (None for all categories)
+
+    Results: GetConfigCategoryResultSuccess (with contents dict) | GetConfigCategoryResultFailure (category not found)
+    """
+
     category: str | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConfigCategoryResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Configuration category retrieved successfully.
+
+    Args:
+        contents: Dictionary of key-value pairs within the category
+    """
+
     contents: dict[str, Any]
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConfigCategoryResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Configuration category retrieval failed. Common causes: category not found, invalid category name."""
 
 
 @dataclass
 @PayloadRegistry.register
 class SetConfigCategoryRequest(RequestPayload):
+    """Set multiple configuration values within a category.
+
+    Use when: Bulk updating configuration settings, restoring configuration sections,
+    applying configuration templates, batch configuration operations.
+
+    Args:
+        contents: Dictionary of key-value pairs to set in the category
+        category: Name of the configuration category (None for default)
+
+    Results: SetConfigCategoryResultSuccess | SetConfigCategoryResultFailure (invalid category, value errors)
+    """
+
     contents: dict[str, Any]
     category: str | None = None
 
@@ -75,46 +133,64 @@ class SetConfigCategoryRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class SetConfigCategoryResultSuccess(ResultPayloadSuccess):
-    pass
+    """Configuration category updated successfully."""
 
 
 @dataclass
 @PayloadRegistry.register
 class SetConfigCategoryResultFailure(ResultPayloadFailure):
-    pass
+    """Configuration category update failed. Common causes: invalid category name, value validation errors."""
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConfigPathRequest(RequestPayload):
-    pass
+    """Get the path to the configuration file.
+
+    Use when: Locating configuration files, debugging configuration issues,
+    implementing configuration backup/restore, displaying configuration info to users.
+
+    Results: GetConfigPathResultSuccess (with path) | GetConfigPathResultFailure (path not available)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConfigPathResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Configuration path retrieved successfully.
+
+    Args:
+        config_path: Path to the configuration file (None if using default/memory config)
+    """
+
     config_path: str | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class GetConfigPathResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Configuration path retrieval failed. Common causes: configuration not initialized, access denied."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ResetConfigRequest(RequestPayload):
-    pass
+    """Reset configuration to default values.
+
+    Use when: Recovering from configuration errors, restoring default settings,
+    clearing user customizations, troubleshooting configuration issues.
+
+    Results: ResetConfigResultSuccess | ResetConfigResultFailure (reset error)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class ResetConfigResultSuccess(ResultPayloadSuccess):
-    pass
+    """Configuration reset successfully to default values."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ResetConfigResultFailure(ResultPayloadFailure):
-    pass
+    """Configuration reset failed. Common causes: file system errors, permission issues, initialization errors."""

griptape_nodes/retained_mode/events/connection_events.py

@@ -13,6 +13,21 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class CreateConnectionRequest(RequestPayload):
+    """Create a connection between two node parameters.
+
+    Use when: Connecting node outputs to inputs, building data flow between nodes,
+    loading saved workflows. Validates type compatibility and connection rules.
+
+    Args:
+        source_parameter_name: Name of the parameter providing the data
+        target_parameter_name: Name of the parameter receiving the data
+        source_node_name: Name of the source node (None for current context)
+        target_node_name: Name of the target node (None for current context)
+        initial_setup: Skip setup work when loading from file
+
+    Results: CreateConnectionResultSuccess | CreateConnectionResultFailure (incompatible types, invalid nodes/parameters)
+    """
+
     source_parameter_name: str
     target_parameter_name: str
     # If node name is None, use the Current Context
@@ -25,18 +40,36 @@ class CreateConnectionRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class CreateConnectionResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Connection created successfully between parameters."""
 
 
 @dataclass
 @PayloadRegistry.register
 class CreateConnectionResultFailure(ResultPayloadFailure):
-    pass
+    """Connection creation failed.
+
+    Common causes: incompatible types, nodes/parameters not found,
+    connection already exists, circular dependency.
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class DeleteConnectionRequest(RequestPayload):
+    """Delete a connection between two node parameters.
+
+    Use when: Removing unwanted connections, restructuring workflows, disconnecting nodes,
+    updating data flow. Cleans up connection state and updates node resolution.
+
+    Args:
+        source_parameter_name: Name of the parameter providing the data
+        target_parameter_name: Name of the parameter receiving the data
+        source_node_name: Name of the source node (None for current context)
+        target_node_name: Name of the target node (None for current context)
+
+    Results: DeleteConnectionResultSuccess | DeleteConnectionResultFailure (connection not found, nodes/parameters not found)
+    """
+
     source_parameter_name: str
     target_parameter_name: str
     # If node name is None, use the Current Context
@@ -47,18 +80,29 @@ class DeleteConnectionRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class DeleteConnectionResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Connection deleted successfully. Connection state cleaned up."""
 
 
 @dataclass
 @PayloadRegistry.register
 class DeleteConnectionResultFailure(ResultPayloadFailure):
-    pass
+    """Connection deletion failed. Common causes: connection not found, nodes/parameters not found."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ListConnectionsForNodeRequest(RequestPayload):
+    """List all connections for a specific node.
+
+    Use when: Inspecting node connectivity, building connection visualizations,
+    debugging data flow, validating workflow structure.
+
+    Args:
+        node_name: Name of the node to list connections for (None for current context)
+
+    Results: ListConnectionsForNodeResultSuccess (with connection lists) | ListConnectionsForNodeResultFailure (node not found)
+    """
+
     # If node name is None, use the Current Context
     node_name: str | None = None
 
@@ -80,6 +124,13 @@ class OutgoingConnection:
 @dataclass
 @PayloadRegistry.register
 class ListConnectionsForNodeResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Node connections retrieved successfully.
+
+    Args:
+        incoming_connections: List of connections feeding into this node
+        outgoing_connections: List of connections from this node to others
+    """
+
     incoming_connections: list[IncomingConnection]
     outgoing_connections: list[OutgoingConnection]
 
@@ -87,4 +138,4 @@ class ListConnectionsForNodeResultSuccess(WorkflowNotAlteredMixin, ResultPayload
 @dataclass
 @PayloadRegistry.register
 class ListConnectionsForNodeResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Node connections listing failed. Common causes: node not found, no current context."""

griptape_nodes/retained_mode/events/context_events.py

@@ -13,34 +13,57 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class SetWorkflowContextRequest(RequestPayload):
+    """Set the current workflow context.
+
+    Use when: Switching between workflows, initializing workflow sessions,
+    setting the active workflow for subsequent operations, workflow navigation.
+
+    Args:
+        workflow_name: Name of the workflow to set as current context
+
+    Results: SetWorkflowContextSuccess | SetWorkflowContextFailure (workflow not found)
+    """
+
     workflow_name: str
 
 
 @dataclass
 @PayloadRegistry.register
 class SetWorkflowContextSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Workflow context set successfully. Subsequent operations will use this workflow."""
 
 
 @dataclass
 @PayloadRegistry.register
 class SetWorkflowContextFailure(WorkflowAlteredMixin, ResultPayloadFailure):
-    pass
+    """Workflow context setting failed. Common causes: workflow not found, invalid workflow name."""
 
 
 @dataclass
 @PayloadRegistry.register
 class GetWorkflowContextRequest(RequestPayload):
-    pass
+    """Get the current workflow context.
+
+    Use when: Checking which workflow is active, displaying current workflow info,
+    validating workflow state, debugging context issues.
+
+    Results: GetWorkflowContextSuccess (with workflow name) | GetWorkflowContextFailure (no context set)
+    """
 
 
 @dataclass
 @PayloadRegistry.register
 class GetWorkflowContextSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Workflow context retrieved successfully.
+
+    Args:
+        workflow_name: Name of the current workflow context (None if no context set)
+    """
+
     workflow_name: str | None
 
 
 @dataclass
 @PayloadRegistry.register
 class GetWorkflowContextFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Workflow context retrieval failed. Common causes: context not initialized, system error."""

griptape_nodes/retained_mode/events/execution_events.py

@@ -17,6 +17,18 @@ from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 @dataclass
 @PayloadRegistry.register
 class ResolveNodeRequest(RequestPayload):
+    """Resolve (execute) a specific node.
+
+    Use when: Running individual nodes, testing node execution, debugging workflows,
+    stepping through execution manually. Validates inputs and runs node logic.
+
+    Args:
+        node_name: Name of the node to resolve/execute
+        debug_mode: Whether to run in debug mode (default: False)
+
+    Results: ResolveNodeResultSuccess | ResolveNodeResultFailure (with validation exceptions)
+    """
+
     node_name: str
     debug_mode: bool = False
 
@@ -24,19 +36,39 @@ class ResolveNodeRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class ResolveNodeResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Node resolved successfully. Node execution completed and outputs are available."""
 
 
 @dataclass
 @PayloadRegistry.register
 class ResolveNodeResultFailure(ResultPayloadFailure):
+    """Node resolution failed. Contains validation errors that prevented execution.
+
+    Args:
+        validation_exceptions: List of validation errors that occurred
+    """
+
     validation_exceptions: list[Exception]
 
 
 @dataclass
 @PayloadRegistry.register
 class StartFlowRequest(RequestPayload):
-    flow_name: str
+    """Start executing a flow.
+
+    Use when: Running workflows, beginning automated execution, testing complete flows.
+    Validates all nodes and begins execution from resolved nodes.
+
+    Args:
+        flow_name: Name of the flow to start (deprecated, use flow_node_name)
+        flow_node_name: Name of the flow node to start
+        debug_mode: Whether to run in debug mode (default: False)
+
+    Results: StartFlowResultSuccess | StartFlowResultFailure (with validation exceptions)
+    """
+
+    # Maintaining flow_name for backwards compatibility. Will be removed in https://github.com/griptape-ai/griptape-nodes/issues/1663
+    flow_name: str | None = None
     flow_node_name: str | None = None
     debug_mode: bool = False
 
@@ -44,37 +76,56 @@ class StartFlowRequest(RequestPayload):
 @dataclass
 @PayloadRegistry.register
 class StartFlowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Flow started successfully. Execution is now running."""
 
 
 @dataclass
 @PayloadRegistry.register
 class StartFlowResultFailure(ResultPayloadFailure):
+    """Flow start failed. Contains validation errors that prevented execution.
+
+    Args:
+        validation_exceptions: List of validation errors that occurred
+    """
+
     validation_exceptions: list[Exception]
 
 
 @dataclass
 @PayloadRegistry.register
 class CancelFlowRequest(RequestPayload):
-    flow_name: str
+    """Cancel a running flow execution.
+
+    Use when: Stopping long-running workflows, handling user cancellation,
+    stopping execution due to errors or changes. Cleanly terminates execution.
+
+    Args:
+        flow_name: Name of the flow to cancel (deprecated)
+
+    Results: CancelFlowResultSuccess | CancelFlowResultFailure (cancellation error)
+    """
+
+    # Maintaining flow_name for backwards compatibility. Will be removed in https://github.com/griptape-ai/griptape-nodes/issues/1663
+    flow_name: str | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class CancelFlowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
-    pass
+    """Flow cancelled successfully. Execution has been terminated."""
 
 
 @dataclass
 @PayloadRegistry.register
 class CancelFlowResultFailure(ResultPayloadFailure):
-    pass
+    """Flow cancellation failed. Common causes: flow not running, cancellation error."""
 
 
 @dataclass
 @PayloadRegistry.register
 class UnresolveFlowRequest(RequestPayload):
-    flow_name: str
+    # Maintaining flow_name for backwards compatibility. Will be removed in https://github.com/griptape-ai/griptape-nodes/issues/1663
+    flow_name: str | None = None
 
 
 @dataclass
@@ -96,7 +147,8 @@ class UnresolveFlowResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class SingleExecutionStepRequest(RequestPayload):
-    flow_name: str
+    # Maintaining flow_name for backwards compatibility. Will be removed in https://github.com/griptape-ai/griptape-nodes/issues/1663
+    flow_name: str | None = None
 
 
 @dataclass
@@ -114,7 +166,8 @@ class SingleExecutionStepResultFailure(ResultPayloadFailure):
 @dataclass
 @PayloadRegistry.register
 class SingleNodeStepRequest(RequestPayload):
-    flow_name: str
+    # Maintaining flow_name for backwards compatibility. Will be removed in https://github.com/griptape-ai/griptape-nodes/issues/1663
+    flow_name: str | None = None
 
 
 @dataclass
@@ -133,7 +186,8 @@ class SingleNodeStepResultFailure(ResolveNodeResultFailure):
 @dataclass
 @PayloadRegistry.register
 class ContinueExecutionStepRequest(RequestPayload):
-    flow_name: str
+    # Maintaining flow_name for backwards compatibility. Will be removed in https://github.com/griptape-ai/griptape-nodes/issues/1663
+    flow_name: str | None = None
 
 
 @dataclass
@@ -151,12 +205,28 @@ class ContinueExecutionStepResultFailure(ResultPayloadFailure):
 @dataclass
 @PayloadRegistry.register
 class GetFlowStateRequest(RequestPayload):
-    flow_name: str
+    """Get the current execution state of a flow.
+
+    Use when: Monitoring execution progress, debugging workflow state,
+    implementing execution UIs, checking which nodes are active.
+
+    Results: GetFlowStateResultSuccess (with control/resolving nodes) | GetFlowStateResultFailure (flow not found)
+    """
+
+    # Maintaining flow_name for backwards compatibility. Will be removed in https://github.com/griptape-ai/griptape-nodes/issues/1663
+    flow_name: str | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class GetFlowStateResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Flow execution state retrieved successfully.
+
+    Args:
+        control_node: Name of the current control node (if any)
+        resolving_node: Name of the node currently being resolved (if any)
+    """
+
     control_node: str | None
     resolving_node: str | None
 
@@ -164,25 +234,40 @@ class GetFlowStateResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
 @dataclass
 @PayloadRegistry.register
 class GetFlowStateResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Flow state retrieval failed. Common causes: flow not found, no current context."""
 
 
 @dataclass
 @PayloadRegistry.register
 class GetIsFlowRunningRequest(RequestPayload):
-    flow_name: str
+    """Check if a flow is currently running.
+
+    Use when: Monitoring execution status, preventing concurrent execution,
+    implementing execution controls, checking if flow can be modified.
+
+    Results: GetIsFlowRunningResultSuccess (with running status) | GetIsFlowRunningResultFailure (flow not found)
+    """
+
+    # Maintaining flow_name for backwards compatibility. Will be removed in https://github.com/griptape-ai/griptape-nodes/issues/1663
+    flow_name: str | None = None
 
 
 @dataclass
 @PayloadRegistry.register
 class GetIsFlowRunningResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Flow running status retrieved successfully.
+
+    Args:
+        is_running: Whether the flow is currently executing
+    """
+
     is_running: bool
 
 
 @dataclass
 @PayloadRegistry.register
 class GetIsFlowRunningResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
-    pass
+    """Flow running status retrieval failed. Common causes: flow not found, no current context."""
 
 
 # Execution Events! These are sent FROM the EE to the User/GUI. HOW MANY DO WE NEED?