vellum-ai 1.7.4__py3-none-any.whl → 1.7.6__py3-none-any.whl

vellum/workflows/runner/runner.py

@@ -74,6 +74,7 @@ from vellum.workflows.references import ExternalInputReference, OutputReference
 from vellum.workflows.references.state_value import StateValueReference
 from vellum.workflows.state.base import BaseState
 from vellum.workflows.state.delta import StateDelta
+from vellum.workflows.types.core import CancelSignal
 from vellum.workflows.types.generics import InputsType, OutputsType, StateType
 
 if TYPE_CHECKING:
@@ -103,7 +104,7 @@ class WorkflowRunner(Generic[StateType]):
         entrypoint_nodes: Optional[RunFromNodeArg] = None,
         external_inputs: Optional[ExternalInputsArg] = None,
         previous_execution_id: Optional[Union[str, UUID]] = None,
-        cancel_signal: Optional[ThreadingEvent] = None,
+        cancel_signal: Optional[CancelSignal] = None,
         node_output_mocks: Optional[MockNodeExecutionArg] = None,
         max_concurrency: Optional[int] = None,
         init_execution_context: Optional[ExecutionContext] = None,
@@ -465,45 +466,11 @@ class WorkflowRunner(Generic[StateType]):
                 parent=execution.parent_context,
             )
         except NodeException as e:
-            logger.info(e)
-            captured_stacktrace = traceback.format_exc()
-
-            yield NodeExecutionRejectedEvent(
-                trace_id=execution.trace_id,
-                span_id=span_id,
-                body=NodeExecutionRejectedBody(
-                    node_definition=node.__class__,
-                    error=e.error,
-                    stacktrace=captured_stacktrace,
-                ),
-                parent=execution.parent_context,
-            )
+            yield self._handle_run_node_exception(e, "Node Exception", execution, span_id, node)
         except WorkflowInitializationException as e:
-            logger.info(e)
-            captured_stacktrace = traceback.format_exc()
-            yield NodeExecutionRejectedEvent(
-                trace_id=execution.trace_id,
-                span_id=span_id,
-                body=NodeExecutionRejectedBody(
-                    node_definition=node.__class__,
-                    error=e.error,
-                    stacktrace=captured_stacktrace,
-                ),
-                parent=execution.parent_context,
-            )
+            yield self._handle_run_node_exception(e, "Workflow Initialization Exception", execution, span_id, node)
         except InvalidExpressionException as e:
-            logger.info(e)
-            captured_stacktrace = traceback.format_exc()
-            yield NodeExecutionRejectedEvent(
-                trace_id=execution.trace_id,
-                span_id=span_id,
-                body=NodeExecutionRejectedBody(
-                    node_definition=node.__class__,
-                    error=e.error,
-                    stacktrace=captured_stacktrace,
-                ),
-                parent=execution.parent_context,
-            )
+            yield self._handle_run_node_exception(e, "Invalid Expression Exception", execution, span_id, node)
         except Exception as e:
             error_message = self._parse_error_message(e)
             if error_message is None:
@@ -528,6 +495,28 @@ class WorkflowRunner(Generic[StateType]):
 
         logger.debug(f"Finished running node: {node.__class__.__name__}")
 
+    def _handle_run_node_exception(
+        self,
+        exception: Union[NodeException, WorkflowInitializationException, InvalidExpressionException],
+        prefix: str,
+        execution: ExecutionContext,
+        span_id: UUID,
+        node: BaseNode[StateType],
+    ) -> NodeExecutionRejectedEvent:
+        logger.info(f"{prefix}: {exception}")
+        captured_stacktrace = traceback.format_exc()
+
+        return NodeExecutionRejectedEvent(
+            trace_id=execution.trace_id,
+            span_id=span_id,
+            body=NodeExecutionRejectedBody(
+                node_definition=node.__class__,
+                error=exception.error,
+                stacktrace=captured_stacktrace,
+            ),
+            parent=execution.parent_context,
+        )
+
     def _parse_error_message(self, exception: Exception) -> Optional[str]:
         try:
             _, _, tb = sys.exc_info()
@@ -799,13 +788,14 @@ class WorkflowRunner(Generic[StateType]):
             parent=self._execution_context.parent_context,
         )
 
-    def _fulfill_workflow_event(self, outputs: OutputsType) -> WorkflowExecutionFulfilledEvent:
+    def _fulfill_workflow_event(self, outputs: OutputsType, final_state: StateType) -> WorkflowExecutionFulfilledEvent:
         return WorkflowExecutionFulfilledEvent(
             trace_id=self._execution_context.trace_id,
             span_id=self._initial_state.meta.span_id,
             body=WorkflowExecutionFulfilledBody(
                 workflow_definition=self.workflow.__class__,
                 outputs=outputs,
+                final_state=final_state,
             ),
             parent=self._execution_context.parent_context,
         )
@@ -961,7 +951,7 @@ class WorkflowRunner(Generic[StateType]):
                     descriptor.instance.resolve(final_state),
                 )
 
-        self._workflow_event_outer_queue.put(self._fulfill_workflow_event(fulfilled_outputs))
+        self._workflow_event_outer_queue.put(self._fulfill_workflow_event(fulfilled_outputs, final_state))
 
     def _run_background_thread(self) -> None:
         state_class = self.workflow.get_state_class()

vellum/workflows/triggers/__init__.py

@@ -0,0 +1,5 @@
+from vellum.workflows.triggers.base import BaseTrigger
+from vellum.workflows.triggers.integration import IntegrationTrigger
+from vellum.workflows.triggers.manual import ManualTrigger
+
+__all__ = ["BaseTrigger", "IntegrationTrigger", "ManualTrigger"]

vellum/workflows/triggers/base.py

@@ -0,0 +1,125 @@
+from abc import ABC, ABCMeta
+from typing import TYPE_CHECKING, Any, Type, cast
+
+if TYPE_CHECKING:
+    from vellum.workflows.graph.graph import Graph, GraphTarget
+
+
+class BaseTriggerMeta(ABCMeta):
+    """
+    Metaclass for BaseTrigger that enables class-level >> operator.
+
+    This allows triggers to be used at the class level, similar to nodes:
+        ManualTrigger >> MyNode  # Class-level, no instantiation
+    """
+
+    def __rshift__(cls, other: "GraphTarget") -> "Graph":  # type: ignore[misc]
+        """
+        Enable Trigger class >> Node syntax (class-level only).
+
+        Args:
+            other: The target to connect to - can be a Node, Graph, or set of Nodes
+
+        Returns:
+            Graph: A graph object with trigger edges
+
+        Examples:
+            ManualTrigger >> MyNode
+            ManualTrigger >> {NodeA, NodeB}
+            ManualTrigger >> (NodeA >> NodeB)
+        """
+        from vellum.workflows.edges.trigger_edge import TriggerEdge
+        from vellum.workflows.graph.graph import Graph
+        from vellum.workflows.nodes.bases.base import BaseNode as BaseNodeClass
+
+        # Cast cls to the proper type for TriggerEdge
+        trigger_cls = cast("Type[BaseTrigger]", cls)
+
+        if isinstance(other, set):
+            # Trigger >> {NodeA, NodeB}
+            trigger_edges = []
+            graph_items = []
+            for item in other:
+                if isinstance(item, type) and issubclass(item, BaseNodeClass):
+                    trigger_edges.append(TriggerEdge(trigger_cls, item))
+                elif isinstance(item, Graph):
+                    # Trigger >> {Graph1, Graph2}
+                    graph_items.append(item)
+                    for entrypoint in item.entrypoints:
+                        trigger_edges.append(TriggerEdge(trigger_cls, entrypoint))
+                else:
+                    raise TypeError(
+                        f"Cannot connect trigger to {type(item).__name__}. " f"Expected BaseNode or Graph in set."
+                    )
+
+            result_graph = Graph.from_trigger_edges(trigger_edges)
+
+            for graph_item in graph_items:
+                result_graph._extend_edges(graph_item.edges)
+                result_graph._terminals.update(graph_item._terminals)
+                for existing_trigger_edge in graph_item._trigger_edges:
+                    if existing_trigger_edge not in result_graph._trigger_edges:
+                        result_graph._trigger_edges.append(existing_trigger_edge)
+
+            return result_graph
+
+        elif isinstance(other, Graph):
+            # Trigger >> Graph
+            edges = [TriggerEdge(trigger_cls, entrypoint) for entrypoint in other.entrypoints]
+            result_graph = Graph.from_trigger_edges(edges)
+            # Also include the edges from the original graph
+            result_graph._extend_edges(other.edges)
+            result_graph._terminals = other._terminals
+            return result_graph
+
+        elif isinstance(other, type) and issubclass(other, BaseNodeClass):
+            # Trigger >> Node
+            edge = TriggerEdge(trigger_cls, other)
+            return Graph.from_trigger_edge(edge)
+
+        else:
+            raise TypeError(
+                f"Cannot connect trigger to {type(other).__name__}. " f"Expected BaseNode, Graph, or set of BaseNodes."
+            )
+
+    def __rrshift__(cls, other: Any) -> "Graph":
+        """
+        Prevent Node >> Trigger class syntax.
+
+        Raises:
+            TypeError: Always, as this operation is not allowed
+        """
+        raise TypeError(
+            f"Cannot create edge targeting trigger {cls.__name__}. "
+            f"Triggers must be at the start of a graph path, not as targets. "
+            f"Did you mean: {cls.__name__} >> {other.__name__ if hasattr(other, '__name__') else other}?"
+        )
+
+
+class BaseTrigger(ABC, metaclass=BaseTriggerMeta):
+    """
+    Base class for workflow triggers - first-class graph elements.
+
+    Triggers define how and when a workflow execution is initiated. They are integrated
+    into the workflow graph using the >> operator and can connect to nodes at the class level.
+
+    Examples:
+        # Class-level usage (consistent with nodes)
+        ManualTrigger >> MyNode
+        ManualTrigger >> {NodeA, NodeB}
+        ManualTrigger >> (NodeA >> NodeB)
+
+    Subclass Hierarchy:
+        - ManualTrigger: Explicit workflow invocation (default)
+        - IntegrationTrigger: External service triggers (base for Slack, GitHub, etc.)
+        - ScheduledTrigger: Time-based triggers with cron/interval schedules
+
+    Important:
+        Triggers can only appear at the start of graph paths. Attempting to create
+        edges targeting triggers (Node >> Trigger) will raise a TypeError.
+
+    Note:
+        Like nodes, triggers work at the class level only. Do not instantiate triggers.
+    """
+
+    pass

vellum/workflows/triggers/integration.py

@@ -0,0 +1,62 @@
+from abc import ABC
+from typing import ClassVar, Optional
+
+from vellum.workflows.outputs.base import BaseOutputs
+from vellum.workflows.triggers.base import BaseTrigger
+
+
+class IntegrationTrigger(BaseTrigger, ABC):
+    """
+    Base class for integration-based triggers (Slack, Email, etc.).
+
+    Integration triggers:
+    - Are initiated by external events (webhooks, API calls)
+    - Produce outputs that downstream nodes can reference
+    - Require configuration (auth, webhooks, etc.)
+
+    Examples:
+        # Define an integration trigger
+        class MyIntegrationTrigger(IntegrationTrigger):
+            class Outputs(IntegrationTrigger.Outputs):
+                data: str
+
+            @classmethod
+            def process_event(cls, event_data: dict):
+                return cls.Outputs(data=event_data.get("data", ""))
+
+        # Use in workflow
+        class MyWorkflow(BaseWorkflow):
+            graph = MyIntegrationTrigger >> ProcessNode
+
+    Note:
+        Unlike ManualTrigger, integration triggers provide structured outputs
+        that downstream nodes can reference directly via Outputs.
+    """
+
+    class Outputs(BaseOutputs):
+        """Base outputs for integration triggers."""
+
+        pass
+
+    # Configuration that can be set at runtime
+    config: ClassVar[Optional[dict]] = None
+
+    @classmethod
+    def process_event(cls, event_data: dict) -> "IntegrationTrigger.Outputs":
+        """
+        Process incoming webhook/event data and return trigger outputs.
+
+        This method should be implemented by subclasses to parse external
+        event payloads (e.g., Slack webhooks, email notifications) into
+        structured trigger outputs.
+
+        Args:
+            event_data: Raw event data from the external system
+
+        Returns:
+            Trigger outputs containing parsed event data
+
+        Raises:
+            NotImplementedError: If subclass doesn't implement this method
+        """
+        raise NotImplementedError(f"{cls.__name__} must implement process_event() method to handle external events")

vellum/workflows/triggers/manual.py

@@ -0,0 +1,37 @@
+from vellum.workflows.triggers.base import BaseTrigger
+
+
+class ManualTrigger(BaseTrigger):
+    """
+    Default trigger representing explicit workflow invocation.
+
+    ManualTrigger is used when workflows are explicitly invoked via:
+    - workflow.run() method calls
+    - workflow.stream() method calls
+    - API calls to execute the workflow
+
+    This is the default trigger for all workflows. When no trigger is specified
+    in a workflow's graph definition, ManualTrigger is implicitly added.
+
+    Examples:
+        # Explicit ManualTrigger (equivalent to implicit)
+        class MyWorkflow(BaseWorkflow):
+            graph = ManualTrigger >> MyNode
+
+        # Implicit ManualTrigger (normalized to above)
+        class MyWorkflow(BaseWorkflow):
+            graph = MyNode
+
+    Characteristics:
+        - Provides no trigger-specific inputs
+        - Always ready to execute when invoked
+        - Simplest trigger type with no configuration
+        - Default behavior for backward compatibility
+
+    Comparison with other triggers:
+        - IntegrationTrigger: Responds to external events (webhooks, API calls)
+        - ScheduledTrigger: Executes based on time/schedule configuration
+        - ManualTrigger: Executes when explicitly called
+    """
+
+    pass

vellum/workflows/triggers/tests/__init__.py

@@ -0,0 +1 @@
+# Tests for workflow triggers

vellum/workflows/triggers/tests/test_integration.py

@@ -0,0 +1,102 @@
+"""Tests for IntegrationTrigger base class."""
+
+import pytest
+
+from vellum.workflows.nodes.bases.base import BaseNode
+from vellum.workflows.triggers.integration import IntegrationTrigger
+
+
+def test_integration_trigger__is_abstract():
+    """IntegrationTrigger cannot be instantiated directly (ABC)."""
+    # WHEN we try to call process_event on IntegrationTrigger directly
+    # THEN it raises NotImplementedError
+    with pytest.raises(NotImplementedError, match="must implement process_event"):
+        IntegrationTrigger.process_event({})
+
+
+def test_integration_trigger__outputs_class_exists():
+    """IntegrationTrigger has Outputs class."""
+    # GIVEN IntegrationTrigger
+    # THEN it has an Outputs class
+    assert hasattr(IntegrationTrigger, "Outputs")
+
+
+def test_integration_trigger__can_be_subclassed():
+    """IntegrationTrigger can be subclassed to create concrete triggers."""
+
+    # GIVEN a concrete implementation of IntegrationTrigger
+    class TestTrigger(IntegrationTrigger):
+        class Outputs(IntegrationTrigger.Outputs):
+            data: str
+
+        @classmethod
+        def process_event(cls, event_data: dict):
+            return cls.Outputs(data=event_data.get("data", ""))
+
+    # WHEN we process an event
+    result = TestTrigger.process_event({"data": "test"})
+
+    # THEN it returns the expected outputs
+    assert result.data == "test"
+
+
+def test_integration_trigger__graph_syntax():
+    """IntegrationTrigger can be used in graph syntax."""
+
+    # GIVEN a concrete trigger and a node
+    class TestTrigger(IntegrationTrigger):
+        class Outputs(IntegrationTrigger.Outputs):
+            value: str
+
+        @classmethod
+        def process_event(cls, event_data: dict):
+            return cls.Outputs(value=event_data.get("value", ""))
+
+    class TestNode(BaseNode):
+        pass
+
+    # WHEN we use trigger >> node syntax
+    graph = TestTrigger >> TestNode
+
+    # THEN a graph is created
+    assert graph is not None
+    assert len(list(graph.trigger_edges)) == 1
+    assert list(graph.trigger_edges)[0].trigger_class == TestTrigger
+    assert list(graph.trigger_edges)[0].to_node == TestNode
+
+
+def test_integration_trigger__multiple_entrypoints():
+    """IntegrationTrigger works with multiple entry points."""
+
+    # GIVEN a trigger and multiple nodes
+    class TestTrigger(IntegrationTrigger):
+        class Outputs(IntegrationTrigger.Outputs):
+            msg: str
+
+        @classmethod
+        def process_event(cls, event_data: dict):
+            return cls.Outputs(msg=event_data.get("msg", ""))
+
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    # WHEN we use trigger >> {nodes} syntax
+    graph = TestTrigger >> {NodeA, NodeB}
+
+    # THEN both nodes are entrypoints
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 2
+    target_nodes = {edge.to_node for edge in trigger_edges}
+    assert target_nodes == {NodeA, NodeB}
+
+
+def test_integration_trigger__config_attribute():
+    """IntegrationTrigger has optional config attribute."""
+
+    # GIVEN IntegrationTrigger
+    # THEN it has a config class variable
+    assert hasattr(IntegrationTrigger, "config")
+    assert IntegrationTrigger.config is None

vellum/workflows/workflows/base.py

@@ -4,7 +4,6 @@ from functools import lru_cache
 import importlib
 import inspect
 import logging
-from threading import Event as ThreadingEvent
 from uuid import UUID, uuid4
 from typing import (
     Any,
@@ -27,6 +26,8 @@ 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
@@ -76,6 +77,7 @@ 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.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
@@ -227,12 +229,12 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
     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,
     ]
@@ -374,7 +376,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         entrypoint_nodes: Optional[RunFromNodeArg] = None,
         external_inputs: Optional[ExternalInputsArg] = None,
         previous_execution_id: Optional[Union[str, UUID]] = None,
-        cancel_signal: Optional[ThreadingEvent] = None,
+        cancel_signal: Optional[CancelSignal] = None,
         node_output_mocks: Optional[MockNodeExecutionArg] = None,
         max_concurrency: Optional[int] = None,
     ) -> TerminalWorkflowEvent:
@@ -402,8 +404,8 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         previous_execution_id: Optional[Union[str, UUID]] = None
             The execution ID of the previous execution to resume from.
 
-        cancel_signal: Optional[ThreadingEvent] = None
-            A threading event that can be used to cancel the Workflow Execution.
+        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`
@@ -493,7 +495,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         entrypoint_nodes: Optional[RunFromNodeArg] = None,
         external_inputs: Optional[ExternalInputsArg] = None,
         previous_execution_id: Optional[Union[str, UUID]] = None,
-        cancel_signal: Optional[ThreadingEvent] = None,
+        cancel_signal: Optional[CancelSignal] = None,
         node_output_mocks: Optional[MockNodeExecutionArg] = None,
         max_concurrency: Optional[int] = None,
     ) -> WorkflowEventStream:
@@ -522,8 +524,8 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         previous_execution_id: Optional[Union[str, UUID]] = None
             The execution ID of the previous execution to resume from.
 
-        cancel_signal: Optional[ThreadingEvent] = None
-            A threading event that can be used to cancel the Workflow Execution.
+        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`
@@ -684,6 +686,10 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         workflow_path = f"{module_path}.workflow"
         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(
@@ -691,9 +697,17 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
                     "Please contact Vellum support for assistance with Workflow configuration."
                 ) from e
             else:
-                raise
-        except (SyntaxError, ImportError, ModuleNotFoundError) as e:
-            raise WorkflowInitializationException(message=f"Failed to load workflow module: {e}") from e
+                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:
+            raise WorkflowInitializationException(message=f"Workflow module not found: {e}") 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("__"):

{vellum_ai-1.7.4.dist-info → vellum_ai-1.7.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vellum-ai
-Version: 1.7.4
+Version: 1.7.6
 Summary: 
 License: MIT
 Requires-Python: >=3.9,<4.0