griptape-nodes 0.55.1__tar.gz → 0.56.0__tar.gz

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: griptape-nodes
-Version: 0.55.1
+Version: 0.56.0
 Summary: Add your description here
 Requires-Dist: griptape>=1.8.2
 Requires-Dist: pydantic>=2.10.6

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "griptape-nodes"
-version = "0.55.1"
+version = "0.56.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12.0, <3.13"

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/src/griptape_nodes/cli/commands/init.py

@@ -55,6 +55,10 @@ def init_command(  # noqa: PLR0913
         bool,
         typer.Option(help="Run init in non-interactive mode (no prompts)."),
     ] = False,
+    hf_token: Annotated[
+        str | None,
+        typer.Option(help="Set the Hugging Face token for downloading gated models."),
+    ] = None,
     config: Annotated[
         list[str] | None,
         typer.Option(
@@ -83,6 +87,7 @@ def init_command(  # noqa: PLR0913
             secret_values=secret_values,
             libraries_sync=libraries_sync,
             bucket_name=bucket_name,
+            hf_token=hf_token,
         )
     )
 
@@ -128,6 +133,7 @@ def _run_init_configuration(config: InitConfig) -> None:
     _handle_workspace_config(config)
     _handle_storage_backend_config(config)
     _handle_bucket_config(config)
+    _handle_hf_token_config(config)
     _handle_advanced_library_config(config)
     _handle_arbitrary_configs(config)
 
@@ -193,6 +199,25 @@ def _handle_bucket_config(config: InitConfig) -> str | None:
     return bucket_id
 
 
+def _handle_hf_token_config(config: InitConfig) -> str | None:
+    """Handle Hugging Face token configuration step."""
+    hf_token = None
+
+    if config.interactive:
+        # First ask if they want to configure an HF token
+        configure_hf_token = _prompt_for_hf_token_configuration()
+        if configure_hf_token:
+            hf_token = _prompt_for_hf_token(default_hf_token=config.hf_token)
+    elif config.hf_token is not None:
+        hf_token = config.hf_token
+
+    if hf_token is not None:
+        secrets_manager.set_secret("HF_TOKEN", hf_token)
+        console.print("[bold green]Hugging Face token set[/bold green]")
+
+    return hf_token
+
+
 def _handle_advanced_library_config(config: InitConfig) -> bool | None:
     """Handle advanced library configuration step."""
     register_advanced_library = config.register_advanced_library
@@ -513,6 +538,69 @@ def _create_new_bucket(bucket_name: str) -> str:
         return bucket_id
 
 
+def _prompt_for_hf_token_configuration() -> bool:
+    """Prompts the user whether to configure a Hugging Face token."""
+    # Check if there's already an HF token configured
+    current_hf_token = secrets_manager.get_secret("HF_TOKEN", should_error_on_not_found=False)
+
+    if current_hf_token:
+        explainer = """[bold cyan]Hugging Face Token Configuration[/bold cyan]
+    You currently have a Hugging Face token configured.
+
+    Hugging Face tokens are used to access gated models from the Hugging Face Hub, such as:
+    - Meta's Llama models
+    - black-forest-labs/FLUX.1-dev
+    - Other restricted or premium models
+
+    Would you like to update your Hugging Face token or keep the current one?"""
+        prompt_text = "Update Hugging Face token?"
+        default_value = False
+    else:
+        explainer = """[bold cyan]Hugging Face Token Configuration[/bold cyan]
+    Would you like to configure a Hugging Face token?
+
+    Hugging Face tokens are used by the model manager to download gated models from the Hugging Face Hub, such as:
+    - Meta's Llama models
+    - black-forest-labs/FLUX.1-dev
+    - Other restricted or premium models
+
+    If you don't plan to use gated models, you can skip this step.
+    You can get a token from https://huggingface.co/settings/tokens
+
+    You can always configure a token later by running the initialization process again."""
+        prompt_text = "Configure Hugging Face token?"
+        default_value = False
+
+    console.print(Panel(explainer, expand=False))
+    return Confirm.ask(prompt_text, default=default_value)
+
+
+def _prompt_for_hf_token(default_hf_token: str | None = None) -> str | None:
+    """Prompts the user for their Hugging Face token."""
+    if default_hf_token is None:
+        default_hf_token = secrets_manager.get_secret("HF_TOKEN", should_error_on_not_found=False)
+
+    explainer = """[bold cyan]Hugging Face Token[/bold cyan]
+    Please enter your Hugging Face token to enable downloading of gated models.
+
+    To get a token:
+    1. Go to https://huggingface.co/settings/tokens
+    2. Create a new token with 'Read' permissions
+    3. Copy and paste the token here
+
+    You can leave this blank to skip token configuration."""
+    console.print(Panel(explainer, expand=False))
+
+    hf_token = Prompt.ask(
+        "Hugging Face Token (optional)",
+        default=default_hf_token or "",
+        show_default=False,
+    )
+
+    # Return None if empty string
+    return hf_token if hf_token.strip() else None
+
+
 def _parse_key_value_pairs(pairs: list[str] | None) -> dict[str, Any] | None:
     """Parse key=value pairs from a list of strings.
 

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/src/griptape_nodes/cli/commands/models.py

@@ -1,6 +1,7 @@
 """Models command for managing AI models."""
 
 import asyncio
+import sys
 from typing import TYPE_CHECKING
 
 import typer
@@ -130,6 +131,7 @@ async def _download_model(
     except Exception as e:
         console.print("[bold red]Model download failed:[/bold red]")
         console.print(f"[red]{e}[/red]")
+        sys.exit(1)
 
 
 async def _list_models() -> None:

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/src/griptape_nodes/cli/shared.py

@@ -22,6 +22,7 @@ class InitConfig:
     secret_values: dict[str, str] | None = None
     libraries_sync: bool | None = None
     bucket_name: str | None = None
+    hf_token: str | None = None
 
 
 # Initialize console

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/src/griptape_nodes/exe_types/core_types.py

@@ -1483,12 +1483,23 @@ class ParameterList(ParameterContainer):
         user_defined: bool = False,
         element_id: str | None = None,
         element_type: str | None = None,
+        # UI convenience parameters
+        collapsed: bool | None = None,
+        child_prefix: str | None = None,
+        grid: bool | None = None,
+        grid_columns: int | None = None,
     ):
         if traits:
             self._original_traits = traits
         else:
             self._original_traits = set()
 
+        # Store the UI convenience parameters
+        self._collapsed = collapsed
+        self._child_prefix = child_prefix
+        self._grid = grid
+        self._grid_columns = grid_columns
+
         # Remember: we're a Parameter, too, just like everybody else.
         super().__init__(
             name=name,
@@ -1511,6 +1522,99 @@ class ParameterList(ParameterContainer):
             element_type=element_type,
         )
 
+    @property
+    def collapsed(self) -> bool | None:
+        return self._collapsed
+
+    @collapsed.setter
+    @BaseNodeElement.emits_update_on_write
+    def collapsed(self, value: bool | None) -> None:
+        self._collapsed = value
+
+    @property
+    def child_prefix(self) -> str | None:
+        return self._child_prefix
+
+    @child_prefix.setter
+    @BaseNodeElement.emits_update_on_write
+    def child_prefix(self, value: str | None) -> None:
+        self._child_prefix = value
+
+    @property
+    def grid(self) -> bool | None:
+        return self._grid
+
+    @grid.setter
+    @BaseNodeElement.emits_update_on_write
+    def grid(self, value: bool | None) -> None:
+        self._grid = value
+
+    @property
+    def grid_columns(self) -> int | None:
+        return self._grid_columns
+
+    @grid_columns.setter
+    @BaseNodeElement.emits_update_on_write
+    def grid_columns(self, value: int | None) -> None:
+        self._grid_columns = value
+
+    @property
+    def ui_options(self) -> dict:
+        """Override ui_options to merge convenience parameters in real-time."""
+        # Get base ui_options from parent
+        base_ui_options = super().ui_options
+
+        # Build convenience options from instance parameters
+        convenience_options = {}
+
+        if self._collapsed is not None:
+            convenience_options["collapsed"] = self._collapsed
+
+        if self._child_prefix is not None:
+            convenience_options["child_prefix"] = self._child_prefix
+
+        if self._grid is not None and self._grid:
+            convenience_options["display"] = "grid"
+
+        if self._grid_columns is not None and self._grid:
+            convenience_options["columns"] = self._grid_columns
+
+        # Merge convenience options with base ui_options
+        return {
+            **base_ui_options,
+            **convenience_options,
+        }
+
+    @ui_options.setter
+    @BaseNodeElement.emits_update_on_write
+    def ui_options(self, value: dict) -> None:
+        """Set ui_options, preserving convenience parameters."""
+        # Extract convenience parameters from the incoming value
+        if "display" in value and value["display"] == "grid":
+            self._grid = True
+            if "columns" in value:
+                self._grid_columns = value["columns"]
+        else:
+            self._grid = False
+
+        if "collapsed" in value:
+            self._collapsed = value["collapsed"]
+
+        if "child_prefix" in value:
+            self._child_prefix = value["child_prefix"]
+
+        # Set the base ui_options (excluding convenience parameters)
+        base_ui_options = {
+            k: v for k, v in value.items() if k not in ["display", "columns", "collapsed", "child_prefix"]
+        }
+        self._ui_options = base_ui_options
+
+    def to_dict(self) -> dict[str, Any]:
+        """Override to_dict to use the merged ui_options."""
+        data = super().to_dict()
+        data["ui_options"] = self.ui_options
+        return data
+
     def _custom_getter_for_property_type(self) -> str:
         base_type = super()._custom_getter_for_property_type()
         result = f"list[{base_type}]"

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/src/griptape_nodes/exe_types/node_types.py

@@ -384,9 +384,7 @@ class BaseNode(ABC):
         for name in names:
             parameter = self.get_parameter_by_name(name)
             if parameter is not None:
-                ui_options = parameter.ui_options
-                ui_options["hide"] = not visible
-                parameter.ui_options = ui_options
+                parameter.ui_options = {**parameter.ui_options, "hide": not visible}
 
     def get_message_by_name_or_element_id(self, element: str) -> ParameterMessage | None:
         element_items = self.root_ui_element.find_elements_by_type(ParameterMessage)
@@ -408,9 +406,7 @@ class BaseNode(ABC):
         for name in names:
             message = self.get_message_by_name_or_element_id(name)
             if message is not None:
-                ui_options = message.ui_options
-                ui_options["hide"] = not visible
-                message.ui_options = ui_options
+                message.ui_options = {**message.ui_options, "hide": not visible}
 
     def hide_message_by_name(self, names: str | list[str]) -> None:
         self._set_message_visibility(names, visible=False)
@@ -727,11 +723,9 @@ class BaseNode(ABC):
                 return param
         return None
 
-    # Abstract method to process the node. Must be defined by the type
     # Must save the values of the output parameters in NodeContext.
-    @abstractmethod
-    def process[T](self) -> AsyncResult | None:
-        pass
+    def process(self) -> AsyncResult | None:
+        raise NotImplementedError
 
     async def aprocess(self) -> None:
         """Async version of process().
@@ -867,7 +861,7 @@ class BaseNode(ABC):
             msg = f"Parameter '{parameter_name} doesn't exist on {self.name}'"
             raise RuntimeError(msg)
 
-    def reorder_elements(self, element_order: list[str | int]) -> None:
+    def reorder_elements(self, element_order: list[str] | list[int] | list[str | int]) -> None:
         """Reorder the elements of this node.
 
         Args:
@@ -1109,7 +1103,10 @@ class TrackedParameterOutputValues(dict[str, Any]):
             keys_to_clear = list(self.keys())
             super().clear()
             for key in keys_to_clear:
-                self._emit_parameter_change_event(key, None, deleted=True)
+                # Some nodes still have values set, even if their output values are cleared
+                # Here, we are emitting an event with those set values, to not misrepresent the values of the parameters in the UI.
+                value = self._node.get_parameter_value(key)
+                self._emit_parameter_change_event(key, value, deleted=True)
 
     def silent_clear(self) -> None:
         """Clear all values without emitting parameter change events."""

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/src/griptape_nodes/machines/control_flow.py

@@ -15,6 +15,7 @@ from griptape_nodes.retained_mode.events.base_events import ExecutionEvent, Exec
 from griptape_nodes.retained_mode.events.execution_events import (
     ControlFlowResolvedEvent,
     CurrentControlNodeEvent,
+    InvolvedNodesEvent,
     SelectedControlOutputEvent,
 )
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
@@ -252,12 +253,21 @@ class ControlFlowMachine(FSM[ControlFlowContext]):
             current_nodes = await self._process_nodes_for_dag(start_node)
         else:
             current_nodes = [start_node]
+            # For control flow/sequential: emit all nodes in flow as involved
         self._context.current_nodes = current_nodes
         # Set entry control parameter for initial node (None for workflow start)
         for node in current_nodes:
             node.set_entry_control_parameter(None)
         # Set up to debug
         self._context.paused = debug_mode
+        flow_manager = GriptapeNodes.FlowManager()
+        flow = flow_manager.get_flow_by_name(self._context.flow_name)
+        involved_nodes = list(flow.nodes.keys())
+        GriptapeNodes.EventManager().put_event(
+            ExecutionGriptapeNodeEvent(
+                wrapped_event=ExecutionEvent(payload=InvolvedNodesEvent(involved_nodes=involved_nodes))
+            )
+        )
         await self.start(ResolveNodeState)  # Begins the flow
 
     async def update(self) -> None:

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/src/griptape_nodes/machines/dag_builder.py

@@ -43,10 +43,12 @@ class DagBuilder:
 
     graphs: dict[str, DirectedGraph]  # Str is the name of the start node associated here.
     node_to_reference: dict[str, DagNode]
+    graph_to_nodes: dict[str, set[str]]  # Track which nodes belong to which graph
 
     def __init__(self) -> None:
         self.graphs = {}
         self.node_to_reference: dict[str, DagNode] = {}
+        self.graph_to_nodes = {}
 
     # Complex with the inner recursive method, but it needs connections and added_nodes.
     def add_node_with_dependencies(self, node: BaseNode, graph_name: str = "default") -> list[BaseNode]:  # noqa: C901
@@ -59,16 +61,15 @@ class DagBuilder:
         if graph is None:
             graph = DirectedGraph()
             self.graphs[graph_name] = graph
+            self.graph_to_nodes[graph_name] = set()
 
         def _add_node_recursive(current_node: BaseNode, visited: set[str], graph: DirectedGraph) -> None:
             if current_node.name in visited:
                 return
             visited.add(current_node.name)
-
             # Skip if already in DAG (use DAG membership, not resolved state)
             if current_node.name in self.node_to_reference:
                 return
-
             # Process dependencies first (depth-first)
             ignore_data_dependencies = False
             # This is specifically for output_selector. Overriding 'initialize_spotlight' doesn't work anymore.
@@ -98,6 +99,10 @@ class DagBuilder:
             dag_node = DagNode(node_reference=current_node, node_state=NodeState.WAITING)
             self.node_to_reference[current_node.name] = dag_node
             graph.add_node(node_for_adding=current_node.name)
+
+            # Track which nodes belong to this graph
+            self.graph_to_nodes[graph_name].add(current_node.name)
+
             # DON'T mark as resolved - that happens during actual execution
             added_nodes.append(current_node)
 
@@ -117,12 +122,19 @@ class DagBuilder:
             graph = DirectedGraph()
             self.graphs[graph_name] = graph
         graph.add_node(node_for_adding=node.name)
+
+        # Track which nodes belong to this graph
+        if graph_name not in self.graph_to_nodes:
+            self.graph_to_nodes[graph_name] = set()
+        self.graph_to_nodes[graph_name].add(node.name)
+
         return dag_node
 
     def clear(self) -> None:
         """Clear all nodes and references from the DAG builder."""
         self.graphs.clear()
         self.node_to_reference.clear()
+        self.graph_to_nodes.clear()
 
     def can_queue_control_node(self, node: DagNode) -> bool:
         if len(self.graphs) == 1:
@@ -205,3 +217,10 @@ class DagBuilder:
                                 return True
 
         return False
+
+    def cleanup_empty_graph_nodes(self, graph_name: str) -> None:
+        """Remove nodes from node_to_reference when their graph becomes empty (only in single node resolution)."""
+        if graph_name in self.graph_to_nodes:
+            for node_name in self.graph_to_nodes[graph_name]:
+                self.node_to_reference.pop(node_name, None)
+            self.graph_to_nodes.pop(graph_name, None)

{griptape_nodes-0.55.1 → griptape_nodes-0.56.0}/src/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-0.55.1 → griptape_nodes-0.56.0}/src/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-0.55.1 → griptape_nodes-0.56.0}/src/griptape_nodes/retained_mode/events/execution_events.py

@@ -225,12 +225,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
@@ -348,6 +346,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):