vellum-ai 0.14.41__py3-none-any.whl → 1.11.2__py3-none-any.whl

vellum/workflows/workflows/base.py

@@ -1,8 +1,10 @@
+from dataclasses import field
 from datetime import datetime
 from functools import lru_cache
 import importlib
 import inspect
-from threading import Event as ThreadingEvent
+import logging
+import sys
 from uuid import UUID, uuid4
 from typing import (
     Any,
@@ -25,10 +27,13 @@ from typing import (
     overload,
 )
 
+from pydantic import ValidationError
+
 from vellum.workflows.edges import Edge
 from vellum.workflows.emitters.base import BaseWorkflowEmitter
 from vellum.workflows.errors import WorkflowError, WorkflowErrorCode
 from vellum.workflows.events.node import (
+    NodeEvent,
     NodeExecutionFulfilledBody,
     NodeExecutionFulfilledEvent,
     NodeExecutionInitiatedBody,
@@ -42,6 +47,7 @@ from vellum.workflows.events.node import (
     NodeExecutionStreamingBody,
     NodeExecutionStreamingEvent,
 )
+from vellum.workflows.events.stream import WorkflowEventGenerator
 from vellum.workflows.events.workflow import (
     GenericWorkflowEvent,
     WorkflowExecutionFulfilledBody,
@@ -59,10 +65,14 @@ from vellum.workflows.events.workflow import (
     WorkflowExecutionStreamingBody,
     WorkflowExecutionStreamingEvent,
 )
+from vellum.workflows.exceptions import WorkflowInitializationException
+from vellum.workflows.executable import BaseExecutable
 from vellum.workflows.graph import Graph
 from vellum.workflows.inputs.base import BaseInputs
+from vellum.workflows.loaders.base import BaseWorkflowFinder
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.nodes.mocks import MockNodeExecutionArg
+from vellum.workflows.nodes.utils import get_unadorned_node
 from vellum.workflows.outputs import BaseOutputs
 from vellum.workflows.resolvers.base import BaseWorkflowResolver
 from vellum.workflows.runner import WorkflowRunner
@@ -70,11 +80,15 @@ from vellum.workflows.runner.runner import ExternalInputsArg, RunFromNodeArg
 from vellum.workflows.state.base import BaseState, StateMeta
 from vellum.workflows.state.context import WorkflowContext
 from vellum.workflows.state.store import Store
+from vellum.workflows.triggers.base import BaseTrigger
+from vellum.workflows.types import CancelSignal
 from vellum.workflows.types.generics import InputsType, StateType
 from vellum.workflows.types.utils import get_original_base
 from vellum.workflows.utils.uuids import uuid4_from_hash
 from vellum.workflows.workflows.event_filters import workflow_event_filter
 
+logger = logging.getLogger(__name__)
+
 
 class _BaseWorkflowMeta(type):
     def __new__(mcs, name: str, bases: Tuple[Type, ...], dct: Dict[str, Any]) -> Any:
@@ -122,47 +136,114 @@ class _BaseWorkflowMeta(type):
                 raise TypeError(f"Unexpected graph type: {graph_item.__class__}")
             return nodes
 
+        def filter_overlapping_nodes_from_unused_graphs(
+            unused_graphs: Set[GraphAttribute], overlapping_nodes: Set[Type[BaseNode]]
+        ) -> Set[GraphAttribute]:
+            filtered_graphs: Set[GraphAttribute] = set()
+
+            for item in unused_graphs:
+                if isinstance(item, Graph):
+                    graph_nodes = set(item.nodes)
+                    overlapping_in_graph = graph_nodes & overlapping_nodes
+
+                    if not overlapping_in_graph:
+                        filtered_graphs.add(item)
+                    else:
+                        non_overlapping_nodes = graph_nodes - overlapping_nodes
+                        for node in non_overlapping_nodes:
+                            filtered_graphs.add(node)
+
+                elif isinstance(item, set):
+                    filtered_nodes: Set[Type[BaseNode]] = set()
+                    filtered_graphs_in_set: Set[Graph] = set()
+
+                    for subitem in item:
+                        if isinstance(subitem, Graph):
+                            graph_nodes = set(subitem.nodes)
+                            overlapping_in_graph = graph_nodes & overlapping_nodes
+
+                            if not overlapping_in_graph:
+                                filtered_graphs_in_set.add(subitem)
+                            else:
+                                non_overlapping_nodes = graph_nodes - overlapping_nodes
+                                filtered_nodes.update(non_overlapping_nodes)
+                        elif isinstance(subitem, type) and issubclass(subitem, BaseNode):
+                            if subitem not in overlapping_nodes:
+                                filtered_nodes.add(subitem)
+                        else:
+                            raise TypeError(f"Unexpected item type in unused_graphs set: {subitem.__class__}")
+
+                    # Add non-empty sets back to filtered_graphs
+                    if filtered_nodes:
+                        filtered_graphs.add(filtered_nodes)
+                    if filtered_graphs_in_set:
+                        filtered_graphs.add(filtered_graphs_in_set)
+
+                elif isinstance(item, type) and issubclass(item, BaseNode):
+                    if item not in overlapping_nodes:
+                        filtered_graphs.add(item)
+                else:
+                    filtered_graphs.add(item)
+
+            return filtered_graphs
+
         graph_nodes = collect_nodes(dct.get("graph", set()))
         unused_nodes = collect_nodes(dct.get("unused_graphs", set()))
 
         overlap = graph_nodes & unused_nodes
         if overlap:
             node_names = [node.__name__ for node in overlap]
-            raise ValueError(f"Node(s) {', '.join(node_names)} cannot appear in both graph and unused_graphs")
+            logger.warning(
+                f"Node(s) {', '.join(node_names)} appear in both graph and unused_graphs. Removing from unused_graphs."
+            )
+
+            # Filter out overlapping nodes from unused_graphs
+            if "unused_graphs" in dct:
+                dct["unused_graphs"] = filter_overlapping_nodes_from_unused_graphs(dct["unused_graphs"], overlap)
 
         cls = super().__new__(mcs, name, bases, dct)
         workflow_class = cast(Type["BaseWorkflow"], cls)
         workflow_class.__id__ = uuid4_from_hash(workflow_class.__qualname__)
+
+        inputs_class = workflow_class.get_inputs_class()
+        if inputs_class is not BaseInputs and inputs_class.__parent_class__ is type(None):
+            inputs_class.__parent_class__ = workflow_class
+
+        workflow_class.Outputs.__parent_class__ = workflow_class
+        workflow_class.__output_ids__ = {
+            ref.name: uuid4_from_hash(f"{workflow_class.__id__}|id|{ref.name}") for ref in workflow_class.Outputs
+        }
+
         return workflow_class
 
 
 GraphAttribute = Union[Type[BaseNode], Graph, Set[Type[BaseNode]], Set[Graph]]
 
 
-class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
-    __id__: UUID = uuid4_from_hash(__qualname__)
+class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_BaseWorkflowMeta):
     graph: ClassVar[GraphAttribute]
     unused_graphs: ClassVar[Set[GraphAttribute]]  # nodes or graphs that are defined but not used in the graph
     emitters: List[BaseWorkflowEmitter]
     resolvers: List[BaseWorkflowResolver]
+    is_dynamic: ClassVar[bool] = False
 
     class Outputs(BaseOutputs):
-        pass
+        __parent_class__: Type["BaseWorkflow"] = field(init=False)
 
     WorkflowEvent = Union[  # type: ignore
         GenericWorkflowEvent,
         WorkflowExecutionInitiatedEvent[InputsType, StateType],  # type: ignore[valid-type]
-        WorkflowExecutionFulfilledEvent[Outputs],
+        WorkflowExecutionFulfilledEvent[Outputs, StateType],  # type: ignore[valid-type]
         WorkflowExecutionSnapshottedEvent[StateType],  # type: ignore[valid-type]
     ]
 
     TerminalWorkflowEvent = Union[
-        WorkflowExecutionFulfilledEvent[Outputs],
+        WorkflowExecutionFulfilledEvent[Outputs, StateType],  # type: ignore[valid-type]
         WorkflowExecutionRejectedEvent,
         WorkflowExecutionPausedEvent,
     ]
 
-    WorkflowEventStream = Generator[WorkflowEvent, None, None]
+    WorkflowEventStream = WorkflowEventGenerator[WorkflowEvent]
 
     def __init__(
         self,
@@ -174,11 +255,21 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
         store: Optional[Store] = None,
     ):
         self._parent_state = parent_state
+        self._context = context or WorkflowContext()
         self.emitters = emitters or (self.emitters if hasattr(self, "emitters") else [])
         self.resolvers = resolvers or (self.resolvers if hasattr(self, "resolvers") else [])
-        self._context = context or WorkflowContext()
-        self._store = store or Store()
+        # Prioritize store type from WorkflowContext to allow subworkflows to inherit EmptyStore
+        # TODO(v2.0.0): Remove the concept of an internal store altogether (important-comment)
+        self._store = store or self._context.store_class()
         self._execution_context = self._context.execution_context
+        self._current_runner: Optional[WorkflowRunner] = None
+
+        # Register context with all emitters
+        for emitter in self.emitters:
+            emitter.register_context(self._context)
+
+        for resolver in self.resolvers:
+            resolver.register_workflow_instance(self)
 
         self.validate()
 
@@ -271,6 +362,14 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
         """
         return cls._get_edges_from_subgraphs(cls.get_unused_subgraphs())
 
+    @classmethod
+    def get_all_nodes(cls) -> Iterator[Type[BaseNode]]:
+        """
+        Returns an iterator over all nodes in the Workflow, used or unused.
+        """
+        yield from cls.get_nodes()
+        yield from cls.get_unused_nodes()
+
     @classmethod
     def get_entrypoints(cls) -> Iterable[Type[BaseNode]]:
         return iter({e for g in cls.get_subgraphs() for e in g.entrypoints})
@@ -282,9 +381,13 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
         state: Optional[StateType] = None,
         entrypoint_nodes: Optional[RunFromNodeArg] = None,
         external_inputs: Optional[ExternalInputsArg] = None,
-        cancel_signal: Optional[ThreadingEvent] = None,
+        previous_execution_id: Optional[Union[str, UUID]] = None,
+        execution_id: Optional[UUID] = None,
+        cancel_signal: Optional[CancelSignal] = None,
         node_output_mocks: Optional[MockNodeExecutionArg] = None,
         max_concurrency: Optional[int] = None,
+        timeout: Optional[float] = None,
+        trigger: Optional[BaseTrigger] = None,
     ) -> TerminalWorkflowEvent:
         """
         Invoke a Workflow, returning the last event emitted, which should be one of:
@@ -307,8 +410,14 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
         external_inputs: Optional[ExternalInputsArg] = None
             External inputs to pass to the Workflow. Useful for providing human-in-the-loop behavior to the Workflow.
 
-        cancel_signal: Optional[ThreadingEvent] = None
-            A threading event that can be used to cancel the Workflow Execution.
+        previous_execution_id: Optional[Union[str, UUID]] = None
+            The execution ID of the previous execution to resume from.
+
+        execution_id: Optional[UUID] = None
+            The execution ID to use for this workflow run. Sets the initial state's span_id for fresh runs.
+
+        cancel_signal: Optional[CancelSignal] = None
+            A cancel signal that can be used to cancel the Workflow Execution.
 
         node_output_mocks: Optional[MockNodeExecutionArg] = None
             A list of Outputs to mock for Nodes during Workflow Execution. Each mock can include a `when_condition`
@@ -318,19 +427,35 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
             The max number of concurrent threads to run the Workflow with. If not provided, the Workflow will run
             without limiting concurrency. This configuration only applies to the current Workflow and not to any
             subworkflows or nodes that utilizes threads.
+
+        timeout: Optional[float] = None
+            The maximum time in seconds to allow the Workflow to run. If the timeout is exceeded, the Workflow
+            will be rejected with a WORKFLOW_TIMEOUT error code and any nodes in flight will be rejected.
+
+        trigger: Optional[BaseTrigger] = None
+            A trigger instance for workflows with triggers (e.g., IntegrationTrigger, ManualTrigger, ScheduledTrigger).
+            The trigger instance is bound to the workflow state, making its attributes accessible to downstream nodes.
+            Required for workflows that only have IntegrationTrigger; optional for workflows with both ManualTrigger
+            and IntegrationTrigger.
         """
 
-        events = WorkflowRunner(
+        runner = WorkflowRunner(
             self,
             inputs=inputs,
             state=state,
             entrypoint_nodes=entrypoint_nodes,
             external_inputs=external_inputs,
+            previous_execution_id=previous_execution_id,
             cancel_signal=cancel_signal,
             node_output_mocks=node_output_mocks,
             max_concurrency=max_concurrency,
+            timeout=timeout,
             init_execution_context=self._execution_context,
-        ).stream()
+            trigger=trigger,
+            execution_id=execution_id,
+        )
+        self._current_runner = runner
+        events = runner.stream()
         first_event: Optional[Union[WorkflowExecutionInitiatedEvent, WorkflowExecutionResumedEvent]] = None
         last_event = None
         for event in events:
@@ -339,7 +464,7 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
             last_event = event
 
         if not last_event:
-            return WorkflowExecutionRejectedEvent(
+            rejected_event = WorkflowExecutionRejectedEvent(
                 trace_id=self._execution_context.trace_id,
                 span_id=uuid4(),
                 body=WorkflowExecutionRejectedBody(
@@ -350,9 +475,10 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
                     workflow_definition=self.__class__,
                 ),
             )
+            return rejected_event
 
         if not first_event:
-            return WorkflowExecutionRejectedEvent(
+            rejected_event = WorkflowExecutionRejectedEvent(
                 trace_id=self._execution_context.trace_id,
                 span_id=uuid4(),
                 body=WorkflowExecutionRejectedBody(
@@ -363,6 +489,7 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
                     workflow_definition=self.__class__,
                 ),
             )
+            return rejected_event
 
         if (
             last_event.name == "workflow.execution.rejected"
@@ -371,7 +498,7 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
         ):
             return last_event
 
-        return WorkflowExecutionRejectedEvent(
+        rejected_event = WorkflowExecutionRejectedEvent(
             trace_id=self._execution_context.trace_id,
             span_id=first_event.span_id,
             body=WorkflowExecutionRejectedBody(
@@ -382,6 +509,7 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
                 ),
             ),
         )
+        return rejected_event
 
     def stream(
         self,
@@ -391,9 +519,13 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
         state: Optional[StateType] = None,
         entrypoint_nodes: Optional[RunFromNodeArg] = None,
         external_inputs: Optional[ExternalInputsArg] = None,
-        cancel_signal: Optional[ThreadingEvent] = None,
+        previous_execution_id: Optional[Union[str, UUID]] = None,
+        execution_id: Optional[UUID] = None,
+        cancel_signal: Optional[CancelSignal] = None,
         node_output_mocks: Optional[MockNodeExecutionArg] = None,
         max_concurrency: Optional[int] = None,
+        timeout: Optional[float] = None,
+        trigger: Optional[BaseTrigger] = None,
     ) -> WorkflowEventStream:
         """
         Invoke a Workflow, yielding events as they are emitted.
@@ -417,8 +549,14 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
         external_inputs: Optional[ExternalInputsArg] = None
             External inputs to pass to the Workflow. Useful for providing human-in-the-loop behavior to the Workflow.
 
-        cancel_signal: Optional[ThreadingEvent] = None
-            A threading event that can be used to cancel the Workflow Execution.
+        previous_execution_id: Optional[Union[str, UUID]] = None
+            The execution ID of the previous execution to resume from.
+
+        execution_id: Optional[UUID] = None
+            The execution ID to use for this workflow run. Sets the initial state's span_id for fresh runs.
+
+        cancel_signal: Optional[CancelSignal] = None
+            A cancel signal that can be used to cancel the Workflow Execution.
 
         node_output_mocks: Optional[MockNodeExecutionArg] = None
             A list of Outputs to mock for Nodes during Workflow Execution. Each mock can include a `when_condition`
@@ -428,22 +566,43 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
             The max number of concurrent threads to run the Workflow with. If not provided, the Workflow will run
             without limiting concurrency. This configuration only applies to the current Workflow and not to any
             subworkflows or nodes that utilizes threads.
+
+        timeout: Optional[float] = None
+            The maximum time in seconds to allow the Workflow to run. If the timeout is exceeded, the Workflow
+            will be rejected with a WORKFLOW_TIMEOUT error code and any nodes in flight will be rejected.
+
+        trigger: Optional[BaseTrigger] = None
+            A trigger instance for workflows with triggers (e.g., IntegrationTrigger, ManualTrigger, ScheduledTrigger).
+            The trigger instance is bound to the workflow state, making its attributes accessible to downstream nodes.
+            Required for workflows that only have IntegrationTrigger; optional for workflows with both ManualTrigger
+            and IntegrationTrigger.
         """
 
         should_yield = event_filter or workflow_event_filter
-        for event in WorkflowRunner(
+        runner = WorkflowRunner(
             self,
             inputs=inputs,
             state=state,
             entrypoint_nodes=entrypoint_nodes,
             external_inputs=external_inputs,
+            previous_execution_id=previous_execution_id,
             cancel_signal=cancel_signal,
             node_output_mocks=node_output_mocks,
             max_concurrency=max_concurrency,
+            timeout=timeout,
             init_execution_context=self._execution_context,
-        ).stream():
-            if should_yield(self.__class__, event):
-                yield event
+            trigger=trigger,
+            execution_id=execution_id,
+        )
+        self._current_runner = runner
+        runner_stream = runner.stream()
+
+        def _generate_filtered_events() -> Generator[BaseWorkflow.WorkflowEvent, None, None]:
+            for event in runner_stream:
+                if should_yield(self.__class__, event):
+                    yield event
+
+        return WorkflowEventGenerator(_generate_filtered_events(), runner_stream.span_id)
 
     def validate(self) -> None:
         """
@@ -453,6 +612,77 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
         # https://app.shortcut.com/vellum/story/4327
         pass
 
+    def _resolve_node_ref(self, node_ref: Union[Type[BaseNode], UUID, str]) -> Type[BaseNode]:
+        """
+        Resolve a node reference (class, UUID, or string) to a node class.
+
+        Args:
+            node_ref: Either a node class, a UUID, or a fully qualified string
+                     in the format "module.ClassName"
+
+        Returns:
+            The resolved node class
+
+        Raises:
+            WorkflowInitializationException: If the node reference cannot be resolved
+        """
+        if inspect.isclass(node_ref) and issubclass(node_ref, BaseNode):
+            return node_ref
+
+        candidate_nodes: List[Type[BaseNode]] = []
+        for node in self.get_all_nodes():
+            candidate_nodes.append(node)
+            wrapped_node = get_unadorned_node(node)
+            if wrapped_node != node:
+                candidate_nodes.append(wrapped_node)
+
+        if isinstance(node_ref, UUID):
+            for node in candidate_nodes:
+                if node.__id__ == node_ref:
+                    return node
+            identifier = str(node_ref)
+            raise WorkflowInitializationException(message=f"Node '{identifier}' not found in workflow")
+
+        if isinstance(node_ref, str):
+            try:
+                module_path, class_name = node_ref.rsplit(".", 1)
+                module = importlib.import_module(module_path)
+                node_class = getattr(module, class_name)
+                if inspect.isclass(node_class) and issubclass(node_class, BaseNode):
+                    return node_class
+                raise WorkflowInitializationException(message=f"Node '{node_ref}' not found in workflow")
+            except (ValueError, ModuleNotFoundError, AttributeError):
+                for node in candidate_nodes:
+                    if f"{node.__module__}.{node.__name__}" == node_ref:
+                        return node
+                raise WorkflowInitializationException(message=f"Node '{node_ref}' not found in workflow")
+
+        raise WorkflowInitializationException(message=f"Node '{node_ref}' not found in workflow")
+
+    def run_node(
+        self, node: Union[Type[BaseNode], UUID, str], *, inputs: Optional[Dict[str, Any]] = None
+    ) -> Generator[NodeEvent, None, None]:
+        """
+        Execute a single node and yield node execution events.
+
+        Args:
+            node: Either a node class, a UUID, or a fully qualified string
+                 in the format "module.ClassName"
+            inputs: Optional inputs to pass to the node
+
+        Yields:
+            NodeEvent: Events emitted during node execution
+
+        Raises:
+            ValueError: If the node reference cannot be resolved
+        """
+        resolved_node = self._resolve_node_ref(node)
+        runner = WorkflowRunner(self)
+        span_id = uuid4()
+        node_instance = resolved_node(state=self.get_default_state(), context=self._context, inputs=inputs)
+
+        return runner.run_node(node=node_instance, span_id=span_id)
+
     @classmethod
     @lru_cache
     def _get_parameterized_classes(
@@ -486,16 +716,22 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
     def get_default_inputs(self) -> InputsType:
         return self.get_inputs_class()()
 
-    def get_default_state(self, workflow_inputs: Optional[InputsType] = None) -> StateType:
-        return self.get_state_class()(
-            meta=StateMeta(
-                parent=self._parent_state,
-                workflow_inputs=workflow_inputs or self.get_default_inputs(),
-                workflow_definition=self.__class__,
-            )
+    def get_default_state(
+        self, workflow_inputs: Optional[InputsType] = None, execution_id: Optional[UUID] = None
+    ) -> StateType:
+        meta = StateMeta(
+            parent=self._parent_state,
+            workflow_inputs=workflow_inputs or self.get_default_inputs(),
+            workflow_definition=self.__class__,
         )
 
-    def get_state_at_node(self, node: Type[BaseNode]) -> StateType:
+        # Makes the uuid factory mocker work this way instead of setting in cosntructor
+        if execution_id:
+            meta.span_id = execution_id
+
+        return self.get_state_class()(meta=meta)
+
+    def get_state_at_node(self, node: Type[BaseNode], execution_id: Optional[UUID] = None) -> StateType:
         event_ts = datetime.min
         for event in self._store.events:
             if event.name == "node.execution.initiated" and event.node_definition == node:
@@ -509,11 +745,11 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
             most_recent_state_snapshot = cast(StateType, snapshot)
 
         if not most_recent_state_snapshot:
-            return self.get_default_state()
+            return self.get_default_state(execution_id=execution_id)
 
         return most_recent_state_snapshot
 
-    def get_most_recent_state(self) -> StateType:
+    def get_most_recent_state(self, execution_id: Optional[UUID] = None) -> StateType:
         most_recent_state_snapshot: Optional[StateType] = None
 
         for snapshot in self._store.state_snapshots:
@@ -524,7 +760,7 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
                 most_recent_state_snapshot = next_state
 
         if not most_recent_state_snapshot:
-            return self.get_default_state()
+            return self.get_default_state(execution_id=execution_id)
 
         return most_recent_state_snapshot
 
@@ -557,10 +793,87 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
 
         return state_class(**state)
 
+    @classmethod
+    def deserialize_trigger(cls, trigger_id: Optional[UUID], inputs: dict) -> Union[InputsType, BaseTrigger]:
+        """
+        Deserialize a trigger from a trigger_id and inputs dict.
+
+        If trigger_id is None, returns an instance of the workflow's Inputs class.
+        Otherwise, finds a trigger class that matches the trigger_id and creates an instance of that.
+
+        Parameters
+        ----------
+        trigger_id: Optional[UUID]
+            The UUID of the trigger class to instantiate. If None, returns workflow Inputs.
+
+        inputs: dict
+            The inputs to pass to the trigger or Inputs constructor.
+
+        Returns
+        -------
+        Union[InputsType, BaseTrigger]
+            Either an instance of the workflow's Inputs class (if trigger_id is None)
+            or an instance of the matching trigger class.
+
+        Raises
+        ------
+        WorkflowInitializationException
+            If trigger_id is provided but no matching trigger class is found in the workflow.
+        """
+        if trigger_id is None:
+            inputs_class = cls.get_inputs_class()
+            return inputs_class(**inputs)
+
+        trigger_classes = []
+        for subgraph in cls.get_subgraphs():
+            for trigger_class in subgraph.triggers:
+                if trigger_class.__id__ == trigger_id:
+                    return trigger_class(**inputs)
+
+                trigger_classes.append(trigger_class)
+
+        raise WorkflowInitializationException(
+            message=f"No trigger class found with id {trigger_id} in workflow {cls.__name__}. "
+            f"Available trigger classes: {[trigger_class.__name__ for trigger_class in trigger_classes]}"
+        )
+
     @staticmethod
     def load_from_module(module_path: str) -> Type["BaseWorkflow"]:
         workflow_path = f"{module_path}.workflow"
-        module = importlib.import_module(workflow_path)
+        try:
+            module = importlib.import_module(workflow_path)
+        except ValidationError as e:
+            raise WorkflowInitializationException(
+                message=f"Pydantic Model Validation defined in Workflow Failed: {e}"
+            ) from e
+        except TypeError as e:
+            if "Unexpected graph type" in str(e) or "unhashable type: 'set'" in str(e):
+                raise WorkflowInitializationException(
+                    message="Invalid graph structure detected. Nested sets or unsupported graph types are not allowed. "
+                    "Please contact Vellum support for assistance with Workflow configuration."
+                ) from e
+            else:
+                raise WorkflowInitializationException(message=f"Type Error raised while loading Workflow: {e}") from e
+        except SyntaxError as e:
+            raise WorkflowInitializationException(message=f"Syntax Error raised while loading Workflow: {e}") from e
+        except ModuleNotFoundError as e:
+            error_message = f"Workflow module not found: {e}"
+            raw_data = None
+            has_namespace_match = False
+            for finder in sys.meta_path:
+                if isinstance(finder, BaseWorkflowFinder):
+                    error_message = finder.format_error_message(error_message)
+                    if hasattr(finder, "namespace") and e.name and finder.namespace in e.name:
+                        has_namespace_match = True
+            if not has_namespace_match:
+                raw_data = {"vellum_on_error_action": "CREATE_CUSTOM_IMAGE"}
+            raise WorkflowInitializationException(message=error_message, raw_data=raw_data) from e
+        except ImportError as e:
+            raise WorkflowInitializationException(message=f"Invalid import found while loading Workflow: {e}") from e
+        except NameError as e:
+            raise WorkflowInitializationException(message=f"Invalid variable reference: {e}") from e
+        except Exception as e:
+            raise WorkflowInitializationException(message=f"Unexpected failure while loading module: {e}") from e
         workflows: List[Type[BaseWorkflow]] = []
         for name in dir(module):
             if name.startswith("__"):
@@ -576,11 +889,22 @@ class BaseWorkflow(Generic[InputsType, StateType], metaclass=_BaseWorkflowMeta):
                 workflows.append(attr)
 
         if len(workflows) == 0:
-            raise ValueError(f"No workflows found in {module_path}")
+            raise WorkflowInitializationException(f"No workflows found in {module_path}")
         elif len(workflows) > 1:
-            raise ValueError(f"Multiple workflows found in {module_path}")
+            raise WorkflowInitializationException(f"Multiple workflows found in {module_path}")
         return workflows[0]
 
+    def join(self) -> None:
+        """
+        Wait for all emitters and runner to complete their background work.
+        This ensures all pending events are processed before the workflow terminates.
+        """
+        if self._current_runner:
+            self._current_runner.join()
+
+        for emitter in self.emitters:
+            emitter.join()
+
 
 WorkflowExecutionInitiatedBody.model_rebuild()
 WorkflowExecutionFulfilledBody.model_rebuild()

vellum/workflows/workflows/event_filters.py

@@ -52,5 +52,18 @@ def root_workflow_event_filter(workflow_definition: Type["BaseWorkflow"], event:
     return event_parent_definition.model_dump() == current_workflow_definition.model_dump()
 
 
+def workflow_sandbox_event_filter(workflow_definition: Type["BaseWorkflow"], event: "WorkflowEvent") -> bool:
+    """
+    Filter designed for Workflow Sandbox interfaces: include all events except
+    workflow.execution.snapshotted events from nested/subworkflows. Only allow
+    snapshotted events when they belong to the root workflow definition.
+    """
+
+    if event.name == "workflow.execution.snapshotted":
+        return event.workflow_definition == workflow_definition
+
+    return True
+
+
 def all_workflow_event_filter(workflow_definition: Type["BaseWorkflow"], event: "WorkflowEvent") -> bool:
     return True