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

griptape_nodes/machines/parallel_resolution.py

@@ -18,6 +18,7 @@ from griptape_nodes.retained_mode.events.base_events import (
 from griptape_nodes.retained_mode.events.execution_events import (
     CurrentControlNodeEvent,
     CurrentDataNodeEvent,
+    InvolvedNodesEvent,
     NodeResolvedEvent,
     ParameterValueUpdateEvent,
 )
@@ -184,19 +185,22 @@ class ExecuteDagState(State):
         context: ParallelResolutionContext, node: BaseNode, network_name: str, flow_manager: FlowManager
     ) -> bool:
         """Check if control flow processing should be skipped."""
+        # Get network once to avoid duplicate lookups
+        if context.dag_builder is None:
+            msg = "DAG builder is not initialized"
+            raise ValueError(msg)
+        network = context.dag_builder.graphs.get(network_name, None)
+        if network is None:
+            msg = f"Network {network_name} not found in DAG builder"
+            raise ValueError(msg)
         if flow_manager.global_single_node_resolution:
+            # Clean up nodes from emptied graphs in single node resolution mode
+            if len(network) == 0 and context.dag_builder is not None:
+                context.dag_builder.cleanup_empty_graph_nodes(network_name)
+                ExecuteDagState._emit_involved_nodes_update(context)
             return True
 
-        if context.dag_builder is not None:
-            network = context.dag_builder.graphs.get(network_name, None)
-            if network is not None and len(network) > 0:
-                return True
-
-        if node.stop_flow:
-            node.stop_flow = False
-            return True
-
-        return False
+        return bool(len(network) > 0 or node.stop_flow)
 
     @staticmethod
     def _process_next_control_node(
@@ -229,6 +233,17 @@ class ExecuteDagState(State):
                 )
             ExecuteDagState._add_and_queue_nodes(context, next_node, network_name)
 
+    @staticmethod
+    def _emit_involved_nodes_update(context: ParallelResolutionContext) -> None:
+        """Emit update of involved nodes based on current DAG state."""
+        if context.dag_builder is not None:
+            involved_nodes = list(context.node_to_reference.keys())
+            GriptapeNodes.EventManager().put_event(
+                ExecutionGriptapeNodeEvent(
+                    wrapped_event=ExecutionEvent(payload=InvolvedNodesEvent(involved_nodes=involved_nodes))
+                )
+            )
+
     @staticmethod
     def _add_and_queue_nodes(context: ParallelResolutionContext, next_node: BaseNode, network_name: str) -> None:
         """Add nodes to DAG and queue them if ready."""

griptape_nodes/node_library/workflow_registry.py

@@ -1,19 +1,45 @@
 from __future__ import annotations
 
+import json
+import logging
 from datetime import datetime  # noqa: TC003 (can't put into type checking block as Pydantic model relies on it)
 from pathlib import Path
-from typing import ClassVar
+from typing import Any, ClassVar
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_serializer, field_validator
 
 from griptape_nodes.node_library.library_registry import (
     LibraryNameAndVersion,  # noqa: TC001 (putting this into type checking causes it to not be defined)
 )
 from griptape_nodes.utils.metaclasses import SingletonMeta
 
+logger = logging.getLogger("griptape_nodes")
+
+# Type aliases for clarity
+type NodeName = str
+type ParameterName = str
+type ParameterAttribute = str
+type ParameterMinimalDict = dict[ParameterAttribute, Any]
+type NodeParametersMapping = dict[NodeName, dict[ParameterName, ParameterMinimalDict]]
+
+
+class WorkflowShape(BaseModel):
+    """This structure reflects the input and output shapes extracted from StartNodes and EndNodes inside of the workflow.
+
+    A workflow may have multiple StartNodes and multiple EndNodes, each contributing their parameters
+    to the overall workflow shape.
+
+    Structure is:
+    - inputs: {start_node_name: {param_name: param_minimal_dict}}
+    - outputs: {end_node_name: {param_name: param_minimal_dict}}
+    """
+
+    inputs: NodeParametersMapping = Field(default_factory=dict)
+    outputs: NodeParametersMapping = Field(default_factory=dict)
+
 
 class WorkflowMetadata(BaseModel):
-    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.7.0"
+    LATEST_SCHEMA_VERSION: ClassVar[str] = "0.8.0"
 
     name: str
     schema_version: str
@@ -27,6 +53,50 @@ class WorkflowMetadata(BaseModel):
     creation_date: datetime | None = Field(default=None)
     last_modified_date: datetime | None = Field(default=None)
     branched_from: str | None = Field(default=None)
+    workflow_shape: WorkflowShape | None = Field(default=None)
+
+    @field_serializer("workflow_shape")
+    def serialize_workflow_shape(self, workflow_shape: WorkflowShape | None) -> str | None:
+        """Serialize WorkflowShape as JSON string to avoid TOML serialization issues.
+
+        The WorkflowShape contains deeply nested dictionaries with None values that are
+        meaningful data (e.g., default_value: None). TOML's nested table format creates
+        unreadable output and tomlkit fails on None values in nested structures.
+        JSON preserves None as null and keeps the data compact and readable.
+        """
+        if workflow_shape is None:
+            return None
+        # Use json.dumps to preserve None values as null, which TOML can handle
+        return json.dumps(workflow_shape.model_dump(), separators=(",", ":"))
+
+    @field_validator("workflow_shape", mode="before")
+    @classmethod
+    def validate_workflow_shape(cls, value: Any) -> WorkflowShape | None:
+        """Deserialize WorkflowShape from JSON string during TOML loading.
+
+        When loading workflow metadata from TOML files, the workflow_shape field
+        is stored as a JSON string that needs to be converted back to a WorkflowShape
+        object. This validator handles the expected input formats:
+        - JSON strings (from TOML deserialization)
+        - WorkflowShape objects (from direct Python construction)
+        - None values (workflows without Start/End nodes)
+
+        If JSON deserialization fails, logs a warning and returns None for graceful
+        degradation, consistent with other metadata parsing failures in this codebase.
+        """
+        if value is None:
+            return None
+        if isinstance(value, WorkflowShape):
+            return value
+        if isinstance(value, str):
+            try:
+                data = json.loads(value)
+                return WorkflowShape(**data)
+            except (json.JSONDecodeError, TypeError, ValueError) as e:
+                logger.error("Failed to deserialize workflow_shape from JSON: %s", e)
+                return None
+        # Unexpected type - let Pydantic's normal validation handle it
+        return value
 
 
 class WorkflowRegistry(metaclass=SingletonMeta):

griptape_nodes/retained_mode/events/agent_events.py

@@ -29,12 +29,14 @@ class RunAgentRequest(RequestPayload):
     Args:
         input: Text input to send to the agent
         url_artifacts: List of URL artifacts to include with the request
+        additional_mcp_servers: List of additional MCP server names to include
 
     Results: RunAgentResultStarted -> RunAgentResultSuccess (with output) | RunAgentResultFailure (execution error)
     """
 
     input: str
     url_artifacts: list[RunAgentRequestArtifact]
+    additional_mcp_servers: list[str] = field(default_factory=list)
 
 
 @dataclass

griptape_nodes/retained_mode/events/base_events.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 import logging
 from abc import ABC, abstractmethod
-from dataclasses import asdict, dataclass, field, is_dataclass
+from dataclasses import asdict, dataclass, field, fields, is_dataclass
 from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
 
 from griptape.artifacts import BaseArtifact
@@ -389,6 +389,21 @@ class EventResult[P: RequestPayload, R: ResultPayload](BaseEvent, ABC):
             bool: True if success, False if failure
         """
 
+    @classmethod
+    def _create_payload_instance(cls, payload_type: type, payload_data: dict[str, Any]) -> Any:
+        """Create a payload instance from data, handling dataclass init=False fields."""
+        if is_dataclass(payload_type):
+            # Filter out fields that have init=False to avoid TypeError
+            init_fields = {f.name for f in fields(payload_type) if f.init}
+            filtered_data = {k: v for k, v in payload_data.items() if k in init_fields}
+            return payload_type(**filtered_data)
+        if issubclass(payload_type, BaseModel):
+            return payload_type.model_validate(payload_data)
+        instance = payload_type()
+        for key, value in payload_data.items():
+            setattr(instance, key, value)
+        return instance
+
     @classmethod
     def from_dict(  # pyright: ignore[reportIncompatibleMethodOverride]
         cls, data: builtins.dict[str, Any], req_payload_type: type[P], res_payload_type: type[R]
@@ -403,28 +418,14 @@ class EventResult[P: RequestPayload, R: ResultPayload](BaseEvent, ABC):
 
         # Process request payload
         if req_payload_type:
-            if is_dataclass(req_payload_type):
-                request_payload = req_payload_type(**request_data)
-            elif issubclass(req_payload_type, BaseModel):
-                request_payload = req_payload_type.model_validate(request_data)
-            else:
-                request_payload = req_payload_type()
-                for key, value in request_data.items():
-                    setattr(request_payload, key, value)
+            request_payload = cls._create_payload_instance(req_payload_type, request_data)
         else:
             msg = f"Cannot create {cls.__name__} without a request payload type"
             raise ValueError(msg)
 
         # Process result payload
         if res_payload_type:
-            if is_dataclass(res_payload_type):
-                result_payload = res_payload_type(**result_data)
-            elif issubclass(res_payload_type, BaseModel):
-                result_payload = res_payload_type.model_validate(result_data)
-            else:
-                result_payload = res_payload_type()
-                for key, value in result_data.items():
-                    setattr(result_payload, key, value)
+            result_payload = cls._create_payload_instance(res_payload_type, result_data)
         else:
             msg = f"Cannot create {cls.__name__} without a result payload type"
             raise ValueError(msg)

griptape_nodes/retained_mode/events/execution_events.py

@@ -4,6 +4,7 @@ from typing import Any
 from griptape_nodes.retained_mode.events.base_events import (
     ExecutionPayload,
     RequestPayload,
+    ResultDetails,
     ResultPayloadFailure,
     ResultPayloadSuccess,
     WorkflowAlteredMixin,
@@ -225,12 +226,10 @@ class GetFlowStateResultSuccess(WorkflowNotAlteredMixin, ResultPayloadSuccess):
     Args:
         control_node: Name of the current control node (if any)
         resolving_node: Name of the node currently being resolved (if any)
-        involved_nodes: Names of nodes that are queued to be executed or have been executed in the current run.
     """
 
     control_nodes: list[str] | None
     resolving_node: list[str] | None
-    involved_nodes: list[str] | None
 
 
 @dataclass
@@ -309,7 +308,8 @@ class ControlFlowResolvedEvent(ExecutionPayload):
 @dataclass
 @PayloadRegistry.register
 class ControlFlowCancelledEvent(ExecutionPayload):
-    pass
+    result_details: ResultDetails | str | None = None
+    exception: Exception | None = None
 
 
 @dataclass
@@ -348,6 +348,18 @@ class NodeFinishProcessEvent(ExecutionPayload):
     node_name: str
 
 
+@dataclass
+@PayloadRegistry.register
+class InvolvedNodesEvent(ExecutionPayload):
+    """Event indicating which nodes are involved in the current execution.
+
+    For parallel resolution: Dynamic list based on DAG builder state
+    For control flow/sequential: All nodes when started, empty when complete
+    """
+
+    involved_nodes: list[str]
+
+
 @dataclass
 @PayloadRegistry.register
 class GriptapeEvent(ExecutionPayload):

griptape_nodes/retained_mode/events/flow_events.py

@@ -1,7 +1,8 @@
 from dataclasses import dataclass
 from typing import Any
 
-from griptape_nodes.node_library.library_registry import LibraryNameAndVersion
+from griptape_nodes.exe_types.node_types import NodeDependencies
+from griptape_nodes.node_library.workflow_registry import WorkflowShape
 from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
     ResultPayloadFailure,
@@ -185,8 +186,6 @@ class SerializedFlowCommands:
     Useful for save/load, copy/paste, etc.
 
     Attributes:
-        node_libraries_used (set[LibraryNameAndVersion]): Set of libraries and versions used by the nodes,
-            including those in child flows.
         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.
@@ -199,8 +198,9 @@ 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.
+        node_dependencies (NodeDependencies): Aggregated dependencies from all nodes in this flow and its sub-flows.
+            Includes referenced workflows, static files, Python imports, and libraries. Used for workflow packaging,
+            dependency resolution, and deployment planning.
     """
 
     @dataclass
@@ -221,7 +221,6 @@ class SerializedFlowCommands:
         target_node_uuid: SerializedNodeCommands.NodeUUID
         target_parameter_name: str
 
-    node_libraries_used: set[LibraryNameAndVersion]
     flow_initialization_command: CreateFlowRequest | ImportWorkflowAsReferencedSubFlowRequest | None
     serialized_node_commands: list[SerializedNodeCommands]
     serialized_connections: list[IndirectConnectionSerialization]
@@ -231,7 +230,7 @@ class SerializedFlowCommands:
     ]
     set_lock_commands_per_node: dict[SerializedNodeCommands.NodeUUID, SetLockNodeStateRequest]
     sub_flows_commands: list["SerializedFlowCommands"]
-    referenced_workflows: set[str]
+    node_dependencies: NodeDependencies
 
 
 @dataclass
@@ -382,3 +381,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.
+    """