griptape-nodes 0.44.0__tar.gz → 0.45.0__tar.gz

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: griptape-nodes
-Version: 0.44.0
+Version: 0.45.0
 Summary: Add your description here
 Requires-Dist: griptape>=1.8.0
 Requires-Dist: pydantic>=2.10.6
@@ -19,6 +19,7 @@ Requires-Dist: imageio-ffmpeg>=0.6.0
 Requires-Dist: mcp[ws]>=1.10.1
 Requires-Dist: binaryornot>=0.4.4
 Requires-Dist: pillow>=11.3.0
+Requires-Dist: watchfiles>=1.1.0
 Requires-Dist: austin-dist>=3.7.0 ; extra == 'profiling'
 Requires-Python: >=3.12.0, <3.13
 Provides-Extra: profiling

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "griptape-nodes"
-version = "0.44.0"
+version = "0.45.0"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.12.0, <3.13"
@@ -23,6 +23,7 @@ dependencies = [
   "mcp[ws]>=1.10.1",
   "binaryornot>=0.4.4",
   "pillow>=11.3.0",
+  "watchfiles>=1.1.0",
 ]
 
 [project.optional-dependencies]

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/__init__.py

@@ -31,6 +31,7 @@ with console.status("Loading Griptape Nodes...") as status:
     from griptape_nodes.retained_mode.managers.config_manager import ConfigManager
     from griptape_nodes.retained_mode.managers.os_manager import OSManager
     from griptape_nodes.retained_mode.managers.secrets_manager import SecretsManager
+    from griptape_nodes.utils.uv_utils import find_uv_bin
     from griptape_nodes.utils.version_utils import get_complete_version_string, get_current_version, get_install_source
 
 CONFIG_DIR = xdg_config_home() / "griptape_nodes"
@@ -808,7 +809,10 @@ def _uninstall_self() -> None:
     # Remove the executable
     console.print("[bold]Removing the executable...[/bold]")
     console.print("[bold yellow]When done, press Enter to exit.[/bold yellow]")
-    os_manager.replace_process(["uv", "tool", "uninstall", "griptape-nodes"])
+
+    # Remove the tool using UV
+    uv_path = find_uv_bin()
+    os_manager.replace_process([uv_path, "tool", "uninstall", "griptape-nodes"])
 
 
 def _parse_key_value_pairs(pairs: list[str] | None) -> dict[str, Any] | None:

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/app/api.py

@@ -13,8 +13,6 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 from rich.logging import RichHandler
 
-from griptape_nodes.retained_mode.events.base_events import EventRequest, deserialize_event
-
 if TYPE_CHECKING:
     from queue import Queue
 
@@ -159,6 +157,8 @@ async def _delete_static_file(file_path: str, static_directory: Annotated[Path,
 
 @app.post("/engines/request")
 async def _create_event(request: Request, queue: Annotated[Queue, Depends(get_event_queue)]) -> None:
+    from .app import _process_api_event
+
     body = await request.json()
     _process_api_event(body, queue)
 
@@ -193,36 +193,3 @@ def start_api(static_directory: Path, queue: Queue) -> None:
     uvicorn.run(
         app, host=STATIC_SERVER_HOST, port=STATIC_SERVER_PORT, log_level=STATIC_SERVER_LOG_LEVEL, log_config=None
     )
-
-
-def _process_api_event(event: dict, event_queue: Queue) -> None:
-    """Process API events and send them to the event queue."""
-    payload = event.get("payload", {})
-
-    try:
-        payload["request"]
-    except KeyError:
-        msg = "Error: 'request' was expected but not found."
-        raise RuntimeError(msg) from None
-
-    try:
-        event_type = payload["event_type"]
-        if event_type != "EventRequest":
-            msg = "Error: 'event_type' was found on request, but did not match 'EventRequest' as expected."
-            raise RuntimeError(msg) from None
-    except KeyError:
-        msg = "Error: 'event_type' not found in request."
-        raise RuntimeError(msg) from None
-
-    # Now attempt to convert it into an EventRequest.
-    try:
-        request_event = deserialize_event(json_data=payload)
-        if not isinstance(request_event, EventRequest):
-            msg = f"Deserialized event is not an EventRequest: {type(request_event)}"
-            raise TypeError(msg)  # noqa: TRY301
-    except Exception as e:
-        msg = f"Unable to convert request JSON into a valid EventRequest object. Error Message: '{e}'"
-        raise RuntimeError(msg) from None
-
-    # Add the event to the queue
-    event_queue.put(request_event)

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/app/app.py

@@ -9,7 +9,7 @@ import sys
 import threading
 from pathlib import Path
 from queue import Queue
-from typing import Any
+from typing import Any, cast
 from urllib.parse import urljoin
 
 from griptape.events import (
@@ -24,9 +24,9 @@ from websockets.asyncio.client import connect
 from websockets.exceptions import ConnectionClosed, WebSocketException
 
 from griptape_nodes.mcp_server.server import main as mcp_server
+from griptape_nodes.retained_mode.events import app_events, execution_events
 
 # This import is necessary to register all events, even if not technically used
-from griptape_nodes.retained_mode.events import app_events, execution_events
 from griptape_nodes.retained_mode.events.base_events import (
     AppEvent,
     EventRequest,
@@ -36,11 +36,14 @@ from griptape_nodes.retained_mode.events.base_events import (
     ExecutionGriptapeNodeEvent,
     GriptapeNodeEvent,
     ProgressEvent,
+    RequestPayload,
+    SkipTheLineMixin,
+    deserialize_event,
 )
 from griptape_nodes.retained_mode.events.logger_events import LogHandlerEvent
 from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
 
-from .api import _process_api_event, start_api
+from .api import start_api
 
 # This is a global event queue that will be used to pass events between threads
 event_queue = Queue()
@@ -395,3 +398,67 @@ def __schedule_async_task(coro: Any) -> None:
         asyncio.run_coroutine_threadsafe(coro, event_loop)
     else:
         logger.warning("Event loop not available for scheduling async task")
+
+
+def _process_api_event(event: dict, event_queue: Queue) -> None:
+    """Process API events and send them to the event queue."""
+    payload = event.get("payload", {})
+
+    try:
+        payload["request"]
+    except KeyError:
+        msg = "Error: 'request' was expected but not found."
+        raise RuntimeError(msg) from None
+
+    try:
+        event_type = payload["event_type"]
+        if event_type != "EventRequest":
+            msg = "Error: 'event_type' was found on request, but did not match 'EventRequest' as expected."
+            raise RuntimeError(msg) from None
+    except KeyError:
+        msg = "Error: 'event_type' not found in request."
+        raise RuntimeError(msg) from None
+
+    # Now attempt to convert it into an EventRequest.
+    try:
+        request_event = deserialize_event(json_data=payload)
+        if not isinstance(request_event, EventRequest):
+            msg = f"Deserialized event is not an EventRequest: {type(request_event)}"
+            raise TypeError(msg)  # noqa: TRY301
+    except Exception as e:
+        msg = f"Unable to convert request JSON into a valid EventRequest object. Error Message: '{e}'"
+        raise RuntimeError(msg) from None
+
+    # Check if the event implements SkipTheLineMixin for priority processing
+    if isinstance(request_event.request, SkipTheLineMixin):
+        # Handle the event immediately without queuing
+        # The request is guaranteed to be a RequestPayload since it passed earlier validation
+        result_payload = GriptapeNodes.handle_request(
+            cast("RequestPayload", request_event.request),
+            response_topic=request_event.response_topic,
+            request_id=request_event.request_id,
+        )
+
+        # Create the result event and emit response immediately
+        if result_payload.succeeded():
+            result_event = EventResultSuccess(
+                request=cast("RequestPayload", request_event.request),
+                request_id=request_event.request_id,
+                result=result_payload,
+                response_topic=request_event.response_topic,
+            )
+            dest_socket = "success_result"
+        else:
+            result_event = EventResultFailure(
+                request=cast("RequestPayload", request_event.request),
+                request_id=request_event.request_id,
+                result=result_payload,
+                response_topic=request_event.response_topic,
+            )
+            dest_socket = "failure_result"
+
+        # Emit the response immediately
+        __schedule_async_task(__emit_message(dest_socket, result_event.json(), topic=result_event.response_topic))
+    else:
+        # Add the event to the queue for normal processing
+        event_queue.put(request_event)

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/app/watch.py

@@ -8,6 +8,8 @@ from typing import Any
 from watchdog.events import PatternMatchingEventHandler
 from watchdog.observers import Observer
 
+from griptape_nodes.utils.uv_utils import find_uv_bin
+
 
 class ReloadHandler(PatternMatchingEventHandler):
     def __init__(
@@ -30,8 +32,9 @@ class ReloadHandler(PatternMatchingEventHandler):
     def start_process(self) -> None:
         if self.process:
             self.process.terminate()
-        self.process = subprocess.Popen(
-            ["uv", "run", "gtn"],  # noqa: S607
+        uv_path = find_uv_bin()
+        self.process = subprocess.Popen(  # noqa: S603
+            [uv_path, "run", "gtn"],
             stdout=sys.stdout,
             stderr=sys.stderr,
         )

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/drivers/storage/base_storage_driver.py

@@ -60,6 +60,43 @@ class BaseStorageDriver(ABC):
         """
         ...
 
+    def upload_file(self, file_name: str, file_content: bytes) -> str:
+        """Upload a file to storage.
+
+        Args:
+            file_name: The name of the file to upload.
+            file_content: The file content as bytes.
+
+        Returns:
+            The URL where the file can be accessed.
+
+        Raises:
+            RuntimeError: If file upload fails.
+        """
+        try:
+            # Get signed upload URL
+            upload_response = self.create_signed_upload_url(file_name)
+
+            # Upload the file using the signed URL
+            response = httpx.request(
+                upload_response["method"],
+                upload_response["url"],
+                content=file_content,
+                headers=upload_response["headers"],
+            )
+            response.raise_for_status()
+
+            # Return the download URL
+            return self.create_signed_download_url(file_name)
+        except httpx.HTTPStatusError as e:
+            msg = f"Failed to upload file {file_name}: {e}"
+            logger.error(msg)
+            raise RuntimeError(msg) from e
+        except Exception as e:
+            msg = f"Unexpected error uploading file {file_name}: {e}"
+            logger.error(msg)
+            raise RuntimeError(msg) from e
+
     def download_file(self, file_name: str) -> bytes:
         """Download a file from the bucket.
 

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/drivers/storage/griptape_cloud_storage_driver.py

@@ -76,7 +76,8 @@ class GriptapeCloudStorageDriver(BaseStorageDriver):
         return {"url": response_data["url"], "headers": response_data.get("headers", {}), "method": "PUT"}
 
     def create_signed_download_url(self, file_name: str) -> str:
-        url = urljoin(self.base_url, f"/api/buckets/{self.bucket_id}/asset-urls/{file_name}")
+        full_file_path = self._get_full_file_path(file_name)
+        url = urljoin(self.base_url, f"/api/buckets/{self.bucket_id}/asset-urls/{full_file_path}")
         try:
             response = httpx.post(url, json={"method": "GET"}, headers=self.headers)
             response.raise_for_status()

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/exe_types/core_types.py

@@ -300,11 +300,28 @@ class BaseNodeElement:
             self._node_context._emit_parameter_lifecycle_event(child)
 
     def remove_child(self, child: BaseNodeElement | str) -> None:
+        """Remove a child element from the hierarchy.
+
+        This method recursively searches through the element hierarchy to find and remove
+        the specified child. When the child is found in a descendant container (e.g., a
+        ParameterList), it delegates to that container's remove_child() method to ensure
+        proper cleanup and event handling (like marking parent nodes as unresolved).
+
+        Args:
+            child: The child element to remove, either as an object or by name string
+        """
         ui_elements: list[BaseNodeElement] = [self]
         for ui_element in ui_elements:
             if child in ui_element._children:
-                child._parent = None
-                ui_element._children.remove(child)
+                # Delegate to the actual parent container's remove_child method.
+                # This ensures specialized containers (like ParameterList) can perform
+                # their specific cleanup logic (e.g., marking parent nodes as unresolved).
+                if ui_element is not self:
+                    ui_element.remove_child(child)
+                else:
+                    # We are the direct parent, so handle removal directly
+                    child._parent = None
+                    ui_element._children.remove(child)
                 break
             ui_elements.extend(ui_element._children)
         if self._node_context is not None and isinstance(child, BaseNodeElement):
@@ -371,8 +388,23 @@ class BaseNodeElement:
         return event_data
 
 
-@dataclass(kw_only=True)
-class ParameterMessage(BaseNodeElement):
+class UIOptionsMixin:
+    """Mixin providing UI options update functionality for classes with ui_options."""
+
+    def update_ui_options_key(self, key: str, value: Any) -> None:
+        """Update a single UI option key."""
+        ui_options = self.ui_options
+        ui_options[key] = value
+        self.ui_options = ui_options
+
+    def update_ui_options(self, updates: dict[str, Any]) -> None:
+        """Update multiple UI options at once."""
+        ui_options = self.ui_options
+        ui_options.update(updates)
+        self.ui_options = ui_options
+
+
+class ParameterMessage(BaseNodeElement, UIOptionsMixin):
     """Represents a UI message element, such as a warning or informational text."""
 
     # Define default titles as a class-level constant
@@ -518,11 +550,21 @@ class ParameterMessage(BaseNodeElement):
         return event_data
 
 
-@dataclass(kw_only=True)
-class ParameterGroup(BaseNodeElement):
+class ParameterGroup(BaseNodeElement, UIOptionsMixin):
     """UI element for a group of parameters."""
 
-    ui_options: dict = field(default_factory=dict)
+    def __init__(self, name: str, ui_options: dict | None = None, **kwargs):
+        super().__init__(name=name, **kwargs)
+        self._ui_options = ui_options or {}
+
+    @property
+    def ui_options(self) -> dict:
+        return self._ui_options
+
+    @ui_options.setter
+    @BaseNodeElement.emits_update_on_write
+    def ui_options(self, value: dict) -> None:
+        self._ui_options = value
 
     def to_dict(self) -> dict[str, Any]:
         """Returns a nested dictionary representation of this node and its children.
@@ -630,7 +672,7 @@ class ParameterBase(BaseNodeElement, ABC):
         pass
 
 
-class Parameter(BaseNodeElement):
+class Parameter(BaseNodeElement, UIOptionsMixin):
     # This is the list of types that the Parameter can accept, either externally or when internally treated as a property.
     # Today, we can accept multiple types for input, but only a single output type.
     tooltip: str | list[dict]  # Default tooltip, can be string or list of dicts
@@ -641,7 +683,11 @@ class Parameter(BaseNodeElement):
     tooltip_as_input: str | list[dict] | None = None
     tooltip_as_property: str | list[dict] | None = None
     tooltip_as_output: str | list[dict] | None = None
+
+    # "settable" here means whether it can be assigned to during regular business operation.
+    # During save/load, this value IS still serialized to save its proper state.
     settable: bool = True
+
     user_defined: bool = False
     _allowed_modes: set = field(
         default_factory=lambda: {
@@ -837,7 +883,10 @@ class Parameter(BaseNodeElement):
             ui_options = ui_options | trait.ui_options_for_trait()
         ui_options = ui_options | self._ui_options
         if self._parent is not None and isinstance(self._parent, ParameterGroup):
-            ui_options = ui_options | self._parent.ui_options
+            # Access the field value directly for ParameterGroup
+            parent_ui_options = getattr(self._parent, "ui_options", {})
+            if isinstance(parent_ui_options, dict):
+                ui_options = ui_options | parent_ui_options
         return ui_options
 
     @ui_options.setter
@@ -1198,6 +1247,23 @@ class ParameterContainer(Parameter, ABC):
             element_type=element_type,
         )
 
+    def __bool__(self) -> bool:
+        """Parameter containers are always truthy, even when empty.
+
+        This overrides Python's default truthiness behavior for containers with __len__().
+        By default, Python makes objects with __len__() falsy when len() == 0, which
+        caused bugs where empty ParameterList/ParameterDictionary objects would fail
+        'if param' checks and fall back to stale cached values instead of computing
+        fresh empty results.
+
+        Unlike standard Python containers, ParameterContainer objects represent
+        parameter structure/definitions rather than just data, so they remain
+        meaningful even when empty.
+
+        See: https://github.com/griptape-ai/griptape-nodes/issues/1799
+        """
+        return True
+
     @abstractmethod
     def add_child_parameter(self) -> Parameter:
         pass
@@ -1329,6 +1395,40 @@ class ParameterList(ParameterContainer):
 
         return param
 
+    def add_child(self, child: BaseNodeElement) -> None:
+        """Override to mark parent node as unresolved when children are added.
+
+        When a ParameterList gains a child parameter, the parent node needs to be
+        marked as unresolved to trigger re-evaluation of the node's state and outputs.
+        """
+        super().add_child(child)
+
+        # Mark the parent node as unresolved since the parameter structure changed
+        if self._node_context is not None:
+            # Import at runtime to avoid circular import
+            from griptape_nodes.exe_types.node_types import NodeResolutionState
+
+            self._node_context.make_node_unresolved(
+                current_states_to_trigger_change_event={NodeResolutionState.RESOLVED, NodeResolutionState.RESOLVING}
+            )
+
+    def remove_child(self, child: BaseNodeElement | str) -> None:
+        """Override to mark parent node as unresolved when children are removed.
+
+        When a ParameterList loses a child parameter, the parent node needs to be
+        marked as unresolved to trigger re-evaluation of the node's state and outputs.
+        """
+        super().remove_child(child)
+
+        # Mark the parent node as unresolved since the parameter structure changed
+        if self._node_context is not None:
+            # Import at runtime to avoid circular import
+            from griptape_nodes.exe_types.node_types import NodeResolutionState
+
+            self._node_context.make_node_unresolved(
+                current_states_to_trigger_change_event={NodeResolutionState.RESOLVED, NodeResolutionState.RESOLVING}
+            )
+
 
 class ParameterKeyValuePair(Parameter):
     def __init__(  # noqa: PLR0913

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/exe_types/node_types.py

@@ -368,8 +368,10 @@ class BaseNode(ABC):
         """
         parameter = self.get_parameter_by_name(param)
         if parameter is not None:
-            trait = parameter.find_element_by_id("Options")
-            if trait and isinstance(trait, Options):
+            # Find the Options trait by type since element_id is a UUID
+            traits = parameter.find_elements_by_type(Options)
+            if traits:
+                trait = traits[0]  # Take the first Options trait
                 trait.choices = choices
 
                 if default in choices:
@@ -378,6 +380,13 @@ class BaseNode(ABC):
                 else:
                     msg = f"Default model '{default}' is not in the provided choices."
                     raise ValueError(msg)
+
+                # Update the manually set UI options to include the new simple_dropdown
+                if hasattr(parameter, "_ui_options") and parameter._ui_options:
+                    parameter._ui_options["simple_dropdown"] = choices
+            else:
+                msg = f"No Options trait found for parameter '{param}'."
+                raise ValueError(msg)
         else:
             msg = f"Parameter '{param}' not found for updating model choices."
             raise ValueError(msg)
@@ -393,9 +402,14 @@ class BaseNode(ABC):
         """
         parameter = self.get_parameter_by_name(param)
         if parameter is not None:
-            trait = parameter.find_element_by_id("Options")
-            if trait and isinstance(trait, Options):
+            # Find the Options trait by type since element_id is a UUID
+            traits = parameter.find_elements_by_type(Options)
+            if traits:
+                trait = traits[0]  # Take the first Options trait
                 parameter.remove_trait(trait)
+            else:
+                msg = f"No Options trait found for parameter '{param}'."
+                raise ValueError(msg)
         else:
             msg = f"Parameter '{param}' not found for removing options trait."
             raise ValueError(msg)
@@ -576,7 +590,7 @@ class BaseNode(ABC):
         param = self.get_parameter_by_name(param_name)
         if param and isinstance(param, ParameterContainer):
             value = handle_container_parameter(self, param)
-            if value:
+            if value is not None:
                 return value
         if param_name in self.parameter_values:
             return self.parameter_values[param_name]

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/node_library/workflow_registry.py

@@ -26,6 +26,7 @@ class WorkflowMetadata(BaseModel):
     is_template: bool | None = False
     creation_date: datetime | None = Field(default=None)
     last_modified_date: datetime | None = Field(default=None)
+    branched_from: str | None = Field(default=None)
 
 
 class WorkflowRegistry(metaclass=SingletonMeta):
@@ -81,6 +82,16 @@ class WorkflowRegistry(metaclass=SingletonMeta):
             raise KeyError(msg)
         return instance._workflows.pop(name)
 
+    @classmethod
+    def get_branches_of_workflow(cls, workflow_name: str) -> list[str]:
+        """Get all workflows that are branches of the specified workflow."""
+        instance = cls()
+        branches = []
+        for name, workflow in instance._workflows.items():
+            if workflow.metadata.branched_from == workflow_name:
+                branches.append(name)
+        return branches
+
 
 class Workflow:
     """A workflow card to be ran."""
@@ -102,6 +113,23 @@ class Workflow:
             msg = f"File path '{complete_path}' does not exist."
             raise ValueError(msg)
 
+    @property
+    def is_synced(self) -> bool:
+        """Check if this workflow is in the synced workflows directory."""
+        from griptape_nodes.retained_mode.griptape_nodes import GriptapeNodes
+
+        config_mgr = GriptapeNodes.ConfigManager()
+        synced_directory = config_mgr.get_config_value("synced_workflows_directory")
+
+        # Get the full path to the synced workflows directory
+        synced_path = config_mgr.get_full_path(synced_directory)
+
+        # Get the complete file path for this workflow
+        complete_file_path = WorkflowRegistry.get_complete_file_path(self.file_path)
+
+        # Check if the workflow file is within the synced directory
+        return Path(complete_file_path).is_relative_to(synced_path)
+
     def get_workflow_metadata(self) -> dict:
         # Convert from the Pydantic schema.
         ret_val = {**self.metadata.model_dump()}
@@ -109,4 +137,5 @@ class Workflow:
         # The schema doesn't have the file path in it, because it is baked into the file itself.
         # Customers of this function need that, so let's stuff it in.
         ret_val["file_path"] = self.file_path
+        ret_val["is_synced"] = self.is_synced
         return ret_val

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/retained_mode/events/app_events.py

@@ -5,6 +5,7 @@ from griptape_nodes.retained_mode.events.base_events import (
     RequestPayload,
     ResultPayloadFailure,
     ResultPayloadSuccess,
+    SkipTheLineMixin,
     WorkflowNotAlteredMixin,
 )
 from griptape_nodes.retained_mode.events.payload_registry import PayloadRegistry
@@ -148,7 +149,7 @@ class AppEndSessionResultFailure(ResultPayloadFailure):
 
 @dataclass
 @PayloadRegistry.register
-class SessionHeartbeatRequest(RequestPayload):
+class SessionHeartbeatRequest(RequestPayload, SkipTheLineMixin):
     """Request clients can use ensure the engine session is still active."""
 
 
@@ -166,7 +167,7 @@ class SessionHeartbeatResultFailure(ResultPayloadFailure):
 
 @dataclass
 @PayloadRegistry.register
-class EngineHeartbeatRequest(RequestPayload):
+class EngineHeartbeatRequest(RequestPayload, SkipTheLineMixin):
     """Request clients can use to discover active engines and their status.
 
     Attributes:

{griptape_nodes-0.44.0 → griptape_nodes-0.45.0}/src/griptape_nodes/retained_mode/events/base_events.py

@@ -62,6 +62,15 @@ class WorkflowNotAlteredMixin:
     altered_workflow_state: bool = field(default=False, init=False)
 
 
+class SkipTheLineMixin:
+    """Mixin for events that should skip the event queue and be processed immediately.
+
+    Events that implement this mixin will be handled directly without being added
+    to the event queue, allowing for priority processing of critical events like
+    heartbeats or other time-sensitive operations.
+    """
+
+
 # Success result payload abstract base class
 @dataclass(kw_only=True)
 class ResultPayloadSuccess(ResultPayload, ABC):