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

griptape_nodes/retained_mode/events/mcp_events.py

@@ -0,0 +1,363 @@
+"""MCP (Model Context Protocol) server management events."""
+
+from dataclasses import dataclass
+from typing import Any, TypedDict
+
+from griptape_nodes.retained_mode.events.base_events import (
+    RequestPayload,
+    ResultPayloadFailure,
+    ResultPayloadSuccess,
+    WorkflowAlteredMixin,
+    WorkflowNotAlteredMixin,
+)
+from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
+
+
+# Type definitions for better clarity
+class MCPServerConfig(TypedDict, total=False):
+    """Configuration for an MCP server."""
+
+    name: str
+    transport: str  # Transport protocol type
+    enabled: bool
+    command: str | None  # Process command for stdio transport
+    args: list[str] | None  # Process arguments for stdio transport
+    env: dict[str, str] | None  # Environment variables for stdio transport
+    cwd: str | None  # Working directory for stdio transport
+    encoding: str  # Text encoding for stdio transport
+    encoding_error_handler: str  # Error handling strategy for stdio transport
+    url: str | None  # Connection URL for HTTP-based transports
+    headers: dict[str, str] | None  # HTTP headers for HTTP-based transports
+    timeout: float | None  # Connection timeout for HTTP-based transports
+    sse_read_timeout: float | None  # Read timeout for SSE transport
+    terminate_on_close: bool  # Session termination behavior for streamable HTTP transport
+    description: str | None
+    capabilities: list[str] | None
+
+
+class MCPServerCapability(TypedDict):
+    """Information about an MCP server capability."""
+
+    name: str
+    description: str | None
+    input_schema: dict[str, Any] | None  # JSON schema for capability inputs
+    output_schema: dict[str, Any] | None  # JSON schema for capability outputs
+
+
+class MCPServerInfo(TypedDict, total=False):
+    """Information about an MCP server."""
+
+    name: str
+    version: str | None  # Server version identifier
+    description: str | None  # Human-readable server description
+    capabilities: list[str] | None  # List of supported capability names
+
+
+# MCP Server Management Events
+
+
+# Capability Discovery Events
+@dataclass
+@PayloadRegistry.register
+class DiscoverMCPServerCapabilitiesRequest(RequestPayload):
+    """Discover capabilities from a running MCP server.
+
+    Args:
+        name: The MCP server identifier to discover capabilities from
+        timeout: Maximum time to wait for server response in seconds
+    """
+
+    name: str
+    timeout: int = 30
+
+
+@dataclass
+@PayloadRegistry.register
+class DiscoverMCPServerCapabilitiesResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """MCP server capabilities discovered successfully."""
+
+    name: str
+    capabilities: list[str]
+    detailed_tools: list[MCPServerCapability] | None = None
+    server_info: MCPServerInfo | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class DiscoverMCPServerCapabilitiesResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Failed to discover MCP server capabilities."""
+
+
+@dataclass
+@PayloadRegistry.register
+class ListMCPServersRequest(RequestPayload):
+    """List all configured MCP servers.
+
+    Args:
+        include_disabled: Whether to include disabled servers in the results
+    """
+
+    include_disabled: bool = False
+
+
+@dataclass
+@PayloadRegistry.register
+class ListMCPServersResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """MCP servers listed successfully."""
+
+    servers: dict[str, MCPServerConfig]
+
+
+@dataclass
+@PayloadRegistry.register
+class ListMCPServersResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Failed to list MCP servers."""
+
+
+@dataclass
+@PayloadRegistry.register
+class GetMCPServerRequest(RequestPayload):
+    """Get configuration for a specific MCP server.
+
+    Args:
+        name: The unique identifier for the MCP server
+    """
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class GetMCPServerResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """MCP server configuration retrieved successfully."""
+
+    server_config: MCPServerConfig
+
+
+@dataclass
+@PayloadRegistry.register
+class GetMCPServerResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Failed to get MCP server configuration."""
+
+
+@dataclass
+@PayloadRegistry.register
+class CreateMCPServerRequest(RequestPayload):
+    """Create a new MCP server configuration.
+
+    Args:
+        name: Unique identifier for the server
+        transport: Transport protocol type
+        command: Process command to start the server (required for stdio transport)
+        args: Process arguments to pass to the command (stdio transport)
+        env: Environment variables for the server process (stdio transport)
+        cwd: Working directory for the server process (stdio transport)
+        encoding: Text encoding for stdio communication
+        encoding_error_handler: Encoding error handling strategy for stdio
+        url: Connection URL for HTTP-based transports
+        headers: HTTP headers for HTTP-based connections
+        timeout: Connection timeout in seconds
+        sse_read_timeout: SSE read timeout in seconds
+        terminate_on_close: Session termination behavior for streamable HTTP transport
+        description: Optional description of the server
+        capabilities: List of server capabilities
+        enabled: Whether the server is enabled by default
+    """
+
+    name: str
+    transport: str = "stdio"
+    enabled: bool = True
+
+    # StdioConnection fields
+    command: str | None = None
+    args: list[str] | None = None
+    env: dict[str, str] | None = None
+    cwd: str | None = None
+    encoding: str = "utf-8"
+    encoding_error_handler: str = "strict"
+
+    # HTTP-based connection fields
+    url: str | None = None
+    headers: dict[str, str] | None = None
+    timeout: float | None = None
+    sse_read_timeout: float | None = None
+    terminate_on_close: bool = True
+
+    # Common fields
+    description: str | None = None
+    capabilities: list[str] | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class CreateMCPServerResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """MCP server created successfully."""
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class CreateMCPServerResultFailure(WorkflowAlteredMixin, ResultPayloadFailure):
+    """Failed to create MCP server."""
+
+
+@dataclass
+@PayloadRegistry.register
+class UpdateMCPServerRequest(RequestPayload):
+    """Update an existing MCP server configuration.
+
+    Args:
+        name: The unique identifier for the MCP server
+        new_name: Updated display name for the server
+        transport: Updated transport protocol type
+        command: Updated process command to start the server (stdio transport)
+        args: Updated process arguments to pass to the command (stdio transport)
+        env: Updated environment variables for the server process (stdio transport)
+        cwd: Updated working directory for the server process (stdio transport)
+        encoding: Updated text encoding for stdio communication
+        encoding_error_handler: Updated encoding error handling strategy for stdio
+        url: Updated connection URL for HTTP-based transports
+        headers: Updated HTTP headers for HTTP-based connections
+        timeout: Updated connection timeout in seconds
+        sse_read_timeout: Updated SSE read timeout in seconds
+        terminate_on_close: Updated session termination behavior for streamable HTTP transport
+        description: Updated description of the server
+        capabilities: Updated list of server capabilities
+    """
+
+    name: str
+    new_name: str | None = None
+    transport: str | None = None
+    enabled: bool | None = None
+
+    # StdioConnection fields
+    command: str | None = None
+    args: list[str] | None = None
+    env: dict[str, str] | None = None
+    cwd: str | None = None
+    encoding: str | None = None
+    encoding_error_handler: str | None = None
+
+    # HTTP-based connection fields
+    url: str | None = None
+    headers: dict[str, str] | None = None
+    timeout: float | None = None
+    sse_read_timeout: float | None = None
+    terminate_on_close: bool | None = None
+
+    # Common fields
+    description: str | None = None
+    capabilities: list[str] | None = None
+
+
+@dataclass
+@PayloadRegistry.register
+class UpdateMCPServerResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """MCP server updated successfully."""
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class UpdateMCPServerResultFailure(WorkflowAlteredMixin, ResultPayloadFailure):
+    """Failed to update MCP server."""
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteMCPServerRequest(RequestPayload):
+    """Delete an MCP server configuration.
+
+    Args:
+        name: The unique identifier for the MCP server to delete
+    """
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteMCPServerResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """MCP server deleted successfully."""
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DeleteMCPServerResultFailure(WorkflowAlteredMixin, ResultPayloadFailure):
+    """Failed to delete MCP server."""
+
+
+@dataclass
+@PayloadRegistry.register
+class EnableMCPServerRequest(RequestPayload):
+    """Enable an MCP server.
+
+    Args:
+        name: The unique identifier for the MCP server to enable
+    """
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class EnableMCPServerResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """MCP server enabled successfully."""
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class EnableMCPServerResultFailure(WorkflowAlteredMixin, ResultPayloadFailure):
+    """Failed to enable MCP server."""
+
+
+@dataclass
+@PayloadRegistry.register
+class DisableMCPServerRequest(RequestPayload):
+    """Disable an MCP server.
+
+    Args:
+        name: The unique identifier for the MCP server to disable
+    """
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DisableMCPServerResultSuccess(WorkflowAlteredMixin, ResultPayloadSuccess):
+    """MCP server disabled successfully."""
+
+    name: str
+
+
+@dataclass
+@PayloadRegistry.register
+class DisableMCPServerResultFailure(WorkflowAlteredMixin, ResultPayloadFailure):
+    """Failed to disable MCP server."""
+
+
+@dataclass
+@PayloadRegistry.register
+class GetEnabledMCPServersRequest(RequestPayload):
+    """Get all enabled MCP servers."""
+
+
+@dataclass
+@PayloadRegistry.register
+class GetEnabledMCPServersResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
+    """Enabled MCP servers retrieved successfully."""
+
+    servers: dict[str, MCPServerConfig]
+
+
+@dataclass
+@PayloadRegistry.register
+class GetEnabledMCPServersResultFailure(WorkflowNotAlteredMixin, ResultPayloadFailure):
+    """Failed to get enabled MCP servers."""

griptape_nodes/retained_mode/events/node_events.py

@@ -4,8 +4,7 @@ from typing import Any, NamedTuple, NewType
 from uuid import uuid4
 
 from griptape_nodes.exe_types.core_types import NodeMessagePayload
-from griptape_nodes.exe_types.node_types import NodeResolutionState
-from griptape_nodes.node_library.library_registry import LibraryNameAndVersion
+from griptape_nodes.exe_types.node_types import NodeDependencies, NodeResolutionState
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
     ResultPayloadFailure,
@@ -409,7 +408,7 @@ class SerializedNodeCommands:
     Attributes:
         create_node_command (CreateNodeRequest): The command to create the node.
         element_modification_commands (list[RequestPayload]): A list of commands to create or modify the elements (including Parameters) of the node.
-        node_library_details (LibraryNameAndVersion): Details of the library and version used by the node.
+        node_dependencies (NodeDependencies): Dependencies that this node has on external resources (workflows, files, imports, libraries).
         node_uuid (NodeUUID): The UUID of this particular node. During deserialization, this UUID will be used to correlate this node's instance
             with the connections and parameter values necessary. We cannot use node name because Griptape Nodes enforces unique names, and we cannot
             predict the name that will be selected upon instantiation. Similarly, the same serialized node may be deserialized multiple times, such
@@ -435,7 +434,7 @@ class SerializedNodeCommands:
 
     create_node_command: CreateNodeRequest
     element_modification_commands: list[RequestPayload]
-    node_library_details: LibraryNameAndVersion
+    node_dependencies: NodeDependencies
     lock_node_command: SetLockNodeStateRequest | None = None
     node_uuid: NodeUUID = field(default_factory=lambda: SerializedNodeCommands.NodeUUID(str(uuid4())))
 

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."""