griptape-nodes 0.55.1__py3-none-any.whl → 0.56.0__py3-none-any.whl

griptape_nodes/retained_mode/events/flow_events.py

@@ -2,6 +2,7 @@ from dataclasses import dataclass
 from typing import Any
 
 from griptape_nodes.node_library.library_registry import LibraryNameAndVersion
+from griptape_nodes.node_library.workflow_registry import WorkflowShape
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
     ResultPayloadFailure,
@@ -382,3 +383,60 @@ class SetFlowMetadataResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
 @PayloadRegistry.register
 class SetFlowMetadataResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
     """Flow metadata update failed. Common causes: flow not found, no current context, invalid metadata."""
+
+
+@dataclass
+@PayloadRegistry.register
+class PackageNodeAsSerializedFlowRequest(RequestPayload):
+    """Package a single node as a complete flow with artificial start and end nodes.
+
+    Creates a serialized flow where:
+    - Start node has output parameters matching the packaged node's incoming connections
+    - End node has input parameters matching the packaged node's outgoing connections
+    - All connections are properly mapped through Start -> Node -> End
+
+    Use when: Creating reusable components, exporting nodes for templates,
+    building sub-workflows from existing nodes, creating packaged functionality.
+
+    Args:
+        node_name: Name of the node to package as a flow (None for current context node)
+        start_node_type: Node type name for the artificial start node (defaults to "StartFlow")
+        end_node_type: Node type name for the artificial end node (defaults to "EndFlow")
+        start_end_specific_library_name: Library name containing the start/end nodes (defaults to "Griptape Nodes Library")
+        entry_control_parameter_name: Name of the control parameter that the package node should be entered from. The generated start node will create a connection to this control parameter. NOTE: if no entry_control_parameter_name is specified, the package will be entered from the first available control input parameter.
+        output_parameter_prefix: Prefix for parameter names on the generated end node to avoid collisions (defaults to "packaged_node_")
+
+    Results: PackageNodeAsSerializedFlowResultSuccess (with serialized flow) | PackageNodeAsSerializedFlowResultFailure (node not found, packaging error)
+    """
+
+    # If None is passed, assumes we're packaging the node in the Current Context
+    node_name: str | None = None
+    start_node_type: str = "StartFlow"
+    end_node_type: str = "EndFlow"
+    start_end_specific_library_name: str = "Griptape Nodes Library"
+    entry_control_parameter_name: str | None = None
+    output_parameter_prefix: str = "packaged_node_"
+
+
+@dataclass
+@PayloadRegistry.register
+class PackageNodeAsSerializedFlowResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Node successfully packaged as serialized flow.
+
+    Args:
+        serialized_flow_commands: The complete serialized flow with StartFlow, target node, and EndFlow
+        workflow_shape: The workflow shape defining inputs and outputs for external callers
+    """
+
+    serialized_flow_commands: SerializedFlowCommands
+    workflow_shape: WorkflowShape
+
+
+@dataclass
+@PayloadRegistry.register
+class PackageNodeAsSerializedFlowResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Node packaging failed.
+
+    Common causes: node not found, no current context, serialization error,
+    connection analysis failed, node has no valid flow context.
+    """

griptape_nodes/retained_mode/events/resource_events.py

@@ -0,0 +1,290 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from griptape_nodes.retained_mode.events.base_events import (
+    RequestPayload,
+    ResultPayloadFailure,
+    ResultPayloadSuccess,
+    WorkflowNotAlteredMixin,
+)
+from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
+
+if TYPE_CHECKING:
+    from griptape_nodes.retained_mode.managers.resource_components.resource_instance import Requirements
+    from griptape_nodes.retained_mode.managers.resource_components.resource_type import ResourceType
+    from griptape_nodes.retained_mode.managers.resource_manager import ResourceStatus
+
+
+# List Registered Resource Types Events
+@dataclass
+@PayloadRegistry.register
+class ListRegisteredResourceTypesRequest(RequestPayload):
+    """List all registered resource types.
+
+    Use when: Discovering what types of resources are available for allocation
+    and management.
+    """
+
+
+@dataclass
+@PayloadRegistry.register
+class ListRegisteredResourceTypesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Registered resource types listed successfully."""
+
+    resource_type_names: list[str]
+
+
+@dataclass
+@PayloadRegistry.register
+class ListRegisteredResourceTypesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Registered resource types listing failed."""
+
+
+# Register Resource Type Events
+@dataclass
+@PayloadRegistry.register
+class RegisterResourceTypeRequest(RequestPayload):
+    """Register a new resource type handler.
+
+    Use when: Adding support for a new type of resource (GPU, CPU, Pipeline, etc.)
+    that the ResourceManager should be able to allocate and manage.
+
+    Args:
+        resource_type: The ResourceType instance to register
+    """
+
+    resource_type: "ResourceType"
+
+
+@dataclass
+@PayloadRegistry.register
+class RegisterResourceTypeResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Resource type registered successfully."""
+
+
+@dataclass
+@PayloadRegistry.register
+class RegisterResourceTypeResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Resource type registration failed. Common causes: resource type already registered, invalid resource type."""
+
+
+# Create Resource Instance Events
+@dataclass
+@PayloadRegistry.register
+class CreateResourceInstanceRequest(RequestPayload):
+    """Create a new resource instance.
+
+    Use when: Creating a new instance of a resource that can be tracked, locked,
+    and managed by the ResourceManager.
+
+    Args:
+        resource_type_name: The name of the resource type to create an instance of
+        capabilities: Dict of capabilities for the new instance
+    """
+
+    resource_type_name: str
+    capabilities: dict[str, Any]
+
+
+@dataclass
+@PayloadRegistry.register
+class CreateResourceInstanceResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Resource instance created successfully."""
+
+    instance_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class CreateResourceInstanceResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Resource instance creation failed. Common causes: invalid capabilities, resource creation error."""
+
+
+# Free Resource Instance Events
+@dataclass
+@PayloadRegistry.register
+class FreeResourceInstanceRequest(RequestPayload):
+    """Free a resource instance.
+
+    Use when: Permanently removing a resource instance from tracking and freeing
+    its resources.
+
+    Args:
+        instance_id: The ID of the instance to free
+        force_unlock: If True, force unlock locked instances. If False, raise exception for locked instances.
+    """
+
+    instance_id: str
+    force_unlock: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class FreeResourceInstanceResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Resource instance freed successfully."""
+
+
+@dataclass
+@PayloadRegistry.register
+class FreeResourceInstanceResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Resource instance freeing failed. Common causes: instance not found, instance locked and force_unlock=False."""
+
+
+# Acquire Resource Lock Events
+@dataclass
+@PayloadRegistry.register
+class AcquireResourceInstanceLockRequest(RequestPayload):
+    """Acquire a lock on an existing resource instance.
+
+    Use when: Attempting to acquire exclusive access to a resource instance that
+    matches specific requirements.
+
+    Args:
+        owner_id: The ID of the entity requesting the lock
+        resource_type_name: The name of the resource type to acquire
+        requirements: Optional requirements the resource must satisfy
+    """
+
+    owner_id: str
+    resource_type_name: str
+    requirements: "Requirements | None" = None
+
+
+@dataclass
+@PayloadRegistry.register
+class AcquireResourceInstanceLockResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Resource instance lock acquired successfully."""
+
+    instance_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class AcquireResourceInstanceLockResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Resource instance lock acquisition failed. Common causes: no compatible instances available, all instances locked."""
+
+
+# Release Resource Lock Events
+@dataclass
+@PayloadRegistry.register
+class ReleaseResourceInstanceLockRequest(RequestPayload):
+    """Release a lock on a resource instance.
+
+    Use when: Releasing exclusive access to a resource instance that was
+    previously acquired.
+
+    Args:
+        instance_id: The ID of the resource instance to release
+        owner_id: The ID of the entity releasing the lock
+    """
+
+    instance_id: str
+    owner_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class ReleaseResourceInstanceLockResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Resource instance lock released successfully."""
+
+
+@dataclass
+@PayloadRegistry.register
+class ReleaseResourceInstanceLockResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Resource instance lock release failed. Common causes: instance not found, not locked by specified owner."""
+
+
+# List Compatible Resource Instances Events
+@dataclass
+@PayloadRegistry.register
+class ListCompatibleResourceInstancesRequest(RequestPayload):
+    """List resource instances compatible with requirements.
+
+    Use when: Discovering what resource instances are available that match
+    specific criteria, without acquiring locks.
+
+    Args:
+        resource_type_name: The name of the resource type to filter by
+        requirements: Optional requirements to match. If None, returns all instances of the type.
+        include_locked: If True, also include locked instances
+    """
+
+    resource_type_name: str
+    requirements: "Requirements | None" = None
+    include_locked: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class ListCompatibleResourceInstancesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Compatible resource instances listed successfully."""
+
+    instance_ids: list[str]
+
+
+@dataclass
+@PayloadRegistry.register
+class ListCompatibleResourceInstancesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Compatible resource instances listing failed. Common causes: invalid resource type, invalid requirements."""
+
+
+# Get Resource Instance Status Events
+@dataclass
+@PayloadRegistry.register
+class GetResourceInstanceStatusRequest(RequestPayload):
+    """Get status information for a resource instance.
+
+    Use when: Checking the current state of a specific resource instance,
+    including capabilities and lock status.
+
+    Args:
+        instance_id: The ID of the instance to get status for
+    """
+
+    instance_id: str
+
+
+@dataclass
+@PayloadRegistry.register
+class GetResourceInstanceStatusResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Resource instance status retrieved successfully."""
+
+    status: "ResourceStatus"
+
+
+@dataclass
+@PayloadRegistry.register
+class GetResourceInstanceStatusResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Resource instance status retrieval failed. Common causes: instance not found."""
+
+
+# List Resource Instances By Type Events
+@dataclass
+@PayloadRegistry.register
+class ListResourceInstancesByTypeRequest(RequestPayload):
+    """List resource instances of a specific type.
+
+    Use when: Listing all instances of a particular resource type for
+    management or monitoring purposes.
+
+    Args:
+        resource_type_name: The name of the resource type to list instances for
+        include_locked: If True, also include locked instances
+    """
+
+    resource_type_name: str
+    include_locked: bool = True
+
+
+@dataclass
+@PayloadRegistry.register
+class ListResourceInstancesByTypeResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Resource instances by type listed successfully."""
+
+    instance_ids: list[str]
+
+
+@dataclass
+@PayloadRegistry.register
+class ListResourceInstancesByTypeResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Resource instances by type listing failed. Common causes: invalid resource type."""

griptape_nodes/retained_mode/events/workflow_events.py

@@ -1,7 +1,8 @@
 from dataclasses import dataclass
-from typing import Literal
+from datetime import datetime
+from typing import TYPE_CHECKING, Literal
 
-from griptape_nodes.node_library.workflow_registry import WorkflowMetadata
+from griptape_nodes.node_library.workflow_registry import WorkflowMetadata, WorkflowShape
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
     ResultPayloadFailure,
@@ -11,6 +12,9 @@ from griptape_nodes.retained_mode.events.base_events import (
 )
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
 
+if TYPE_CHECKING:
+    from griptape_nodes.retained_mode.events.flow_events import SerializedFlowCommands
+
 
 @dataclass
 @PayloadRegistry.register
@@ -632,3 +636,54 @@ class RegisterWorkflowsFromConfigResultSuccess(WorkflowNotAlteredMixin, ResultPa
 @PayloadRegistry.register
 class RegisterWorkflowsFromConfigResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
     """Workflow registration from configuration failed. Common causes: configuration not found, invalid paths, registration errors."""
+
+
+@dataclass
+@PayloadRegistry.register
+class SaveWorkflowFileFromSerializedFlowRequest(RequestPayload):
+    """Save a workflow file from serialized flow commands without registry overhead.
+
+    Use when: Creating workflow files from user-supplied subsets of existing workflows,
+    exporting partial workflows, creating standalone workflow files without registration.
+
+    Args:
+        serialized_flow_commands: The serialized commands representing the workflow structure
+        file_name: Name for the workflow file (without .py extension)
+        creation_date: Optional creation date for the workflow metadata (defaults to current time if not provided)
+        image_path: Optional path to workflow image/thumbnail
+        execution_flow_name: Optional flow name to use for execution code (defaults to file_name if not provided)
+        branched_from: Optional branched from information to preserve workflow lineage
+        workflow_shape: Optional workflow shape defining inputs and outputs for external callers
+        file_path: Optional specific file path to use (defaults to workspace path if not provided)
+
+    Results: SaveWorkflowFileFromSerializedFlowResultSuccess (with file path) | SaveWorkflowFileFromSerializedFlowResultFailure (save error)
+    """
+
+    serialized_flow_commands: "SerializedFlowCommands"
+    file_name: str
+    file_path: str | None = None
+    creation_date: datetime | None = None
+    image_path: str | None = None
+    execution_flow_name: str | None = None
+    branched_from: str | None = None
+    workflow_shape: WorkflowShape | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class SaveWorkflowFileFromSerializedFlowResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Workflow file saved successfully from serialized flow commands.
+
+    Args:
+        file_path: Path where the workflow file was written
+        workflow_metadata: The metadata that was generated for the workflow
+    """
+
+    file_path: str
+    workflow_metadata: WorkflowMetadata
+
+
+@dataclass
+@PayloadRegistry.register
+class SaveWorkflowFileFromSerializedFlowResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Workflow file save failed. Common causes: file system error, permission denied, invalid serialized commands."""

griptape_nodes/retained_mode/griptape_nodes.py

@@ -69,6 +69,7 @@ if TYPE_CHECKING:
         OperationDepthManager,
     )
     from griptape_nodes.retained_mode.managers.os_manager import OSManager
+    from griptape_nodes.retained_mode.managers.resource_manager import ResourceManager
     from griptape_nodes.retained_mode.managers.secrets_manager import SecretsManager
     from griptape_nodes.retained_mode.managers.session_manager import SessionManager
     from griptape_nodes.retained_mode.managers.static_files_manager import (
@@ -149,9 +150,10 @@ class GriptapeNodes(metaclass=SingletonMeta):
     _version_compatibility_manager: VersionCompatibilityManager
     _session_manager: SessionManager
     _engine_identity_manager: EngineIdentityManager
+    _resource_manager: ResourceManager
     _sync_manager: SyncManager
 
-    def __init__(self) -> None:
+    def __init__(self) -> None:  # noqa: PLR0915
         from griptape_nodes.retained_mode.managers.agent_manager import AgentManager
         from griptape_nodes.retained_mode.managers.arbitrary_code_exec_manager import (
             ArbitraryCodeExecManager,
@@ -169,6 +171,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
             OperationDepthManager,
         )
         from griptape_nodes.retained_mode.managers.os_manager import OSManager
+        from griptape_nodes.retained_mode.managers.resource_manager import ResourceManager
         from griptape_nodes.retained_mode.managers.secrets_manager import SecretsManager
         from griptape_nodes.retained_mode.managers.session_manager import SessionManager
         from griptape_nodes.retained_mode.managers.static_files_manager import (
@@ -188,6 +191,7 @@ class GriptapeNodes(metaclass=SingletonMeta):
         # Initialize only if our managers haven't been created yet
         if not hasattr(self, "_event_manager"):
             self._event_manager = EventManager()
+            self._resource_manager = ResourceManager(self._event_manager)
             self._config_manager = ConfigManager(self._event_manager)
             self._os_manager = OSManager(self._event_manager)
             self._secrets_manager = SecretsManager(self._config_manager, self._event_manager)
@@ -374,6 +378,10 @@ class GriptapeNodes(metaclass=SingletonMeta):
     def EngineIdentityManager(cls) -> EngineIdentityManager:
         return GriptapeNodes.get_instance()._engine_identity_manager
 
+    @classmethod
+    def ResourceManager(cls) -> ResourceManager:
+        return GriptapeNodes.get_instance()._resource_manager
+
     @classmethod
     def SyncManager(cls) -> SyncManager:
         return GriptapeNodes.get_instance()._sync_manager