vellum-ai 1.7.3__py3-none-any.whl → 1.7.5__py3-none-any.whl

vellum/workflows/events/workflow.py

@@ -137,22 +137,34 @@ class WorkflowExecutionStreamingEvent(_BaseWorkflowEvent):
         return self.body.output
 
 
-class WorkflowExecutionFulfilledBody(_BaseWorkflowExecutionBody, Generic[OutputsType]):
+class WorkflowExecutionFulfilledBody(_BaseWorkflowExecutionBody, Generic[OutputsType, StateType]):
     outputs: OutputsType
+    final_state: Optional[StateType] = None
 
     @field_serializer("outputs")
     def serialize_outputs(self, outputs: OutputsType, _info: Any) -> Dict[str, Any]:
         return default_serializer(outputs)
 
+    @field_serializer("final_state")
+    def serialize_final_state(self, final_state: Optional[StateType], _info: Any) -> Optional[Dict[str, Any]]:
+        if final_state is None:
+            return None
+        state_dict = {k: v for k, v in final_state if k != "meta"}
+        return default_serializer(state_dict)
 
-class WorkflowExecutionFulfilledEvent(_BaseWorkflowEvent, Generic[OutputsType]):
+
+class WorkflowExecutionFulfilledEvent(_BaseWorkflowEvent, Generic[OutputsType, StateType]):
     name: Literal["workflow.execution.fulfilled"] = "workflow.execution.fulfilled"
-    body: WorkflowExecutionFulfilledBody[OutputsType]
+    body: WorkflowExecutionFulfilledBody[OutputsType, StateType]
 
     @property
     def outputs(self) -> OutputsType:
         return self.body.outputs
 
+    @property
+    def final_state(self) -> Optional[StateType]:
+        return self.body.final_state
+
 
 class WorkflowExecutionRejectedBody(_BaseWorkflowExecutionBody):
     error: WorkflowError

vellum/workflows/exceptions.py

@@ -25,10 +25,12 @@ class NodeException(Exception):
         message: str,
         code: WorkflowErrorCode = WorkflowErrorCode.INTERNAL_ERROR,
         raw_data: Optional[Dict[str, Any]] = None,
+        stacktrace: Optional[str] = None,
     ):
         self.message = message
         self.code = code
         self.raw_data = raw_data
+        self.stacktrace = stacktrace
         super().__init__(message)
 
     @property
@@ -37,11 +39,17 @@ class NodeException(Exception):
             message=self.message,
             code=self.code,
             raw_data=self.raw_data,
+            stacktrace=self.stacktrace,
         )
 
     @staticmethod
     def of(workflow_error: WorkflowError) -> "NodeException":
-        return NodeException(message=workflow_error.message, code=workflow_error.code, raw_data=workflow_error.raw_data)
+        return NodeException(
+            message=workflow_error.message,
+            code=workflow_error.code,
+            raw_data=workflow_error.raw_data,
+            stacktrace=workflow_error.stacktrace,
+        )
 
 
 class WorkflowInitializationException(Exception):

vellum/workflows/graph/graph.py

@@ -3,11 +3,13 @@ from typing import TYPE_CHECKING, Iterator, List, Optional, Set, Type, Union
 from orderly_set import OrderedSet
 
 from vellum.workflows.edges.edge import Edge
+from vellum.workflows.edges.trigger_edge import TriggerEdge
 from vellum.workflows.types.generics import NodeType
 
 if TYPE_CHECKING:
     from vellum.workflows.nodes.bases.base import BaseNode
     from vellum.workflows.ports.port import Port
+    from vellum.workflows.triggers.base import BaseTrigger
 
 
 class NoPortsNode:
@@ -46,16 +48,19 @@ class Graph:
     _entrypoints: Set[Union["Port", "NoPortsNode"]]
     _edges: List[Edge]
     _terminals: Set[Union["Port", "NoPortsNode"]]
+    _trigger_edges: List[TriggerEdge]
 
     def __init__(
         self,
         entrypoints: Set[Union["Port", "NoPortsNode"]],
         edges: List[Edge],
         terminals: Set[Union["Port", "NoPortsNode"]],
+        trigger_edges: Optional[List[TriggerEdge]] = None,
     ):
         self._edges = edges
         self._entrypoints = entrypoints
         self._terminals = terminals
+        self._trigger_edges = trigger_edges or []
 
     @staticmethod
     def from_port(port: "Port") -> "Graph":
@@ -96,12 +101,79 @@ class Graph:
     def from_edge(edge: Edge) -> "Graph":
         return Graph(entrypoints={edge.from_port}, edges=[edge], terminals={port for port in edge.to_node.Ports})
 
+    @staticmethod
+    def from_trigger_edge(edge: TriggerEdge) -> "Graph":
+        """
+        Create a graph from a single TriggerEdge (Trigger >> Node).
+
+        Args:
+            edge: TriggerEdge connecting a trigger to a node
+
+        Returns:
+            Graph with the trigger edge and the target node's ports as terminals
+        """
+        ports = {port for port in edge.to_node.Ports}
+        if not ports:
+            no_ports_node = NoPortsNode(edge.to_node)
+            return Graph(
+                entrypoints={no_ports_node},
+                edges=[],
+                terminals={no_ports_node},
+                trigger_edges=[edge],
+            )
+        return Graph(
+            entrypoints=set(ports),
+            edges=[],
+            terminals=set(ports),
+            trigger_edges=[edge],
+        )
+
+    @staticmethod
+    def from_trigger_edges(edges: List[TriggerEdge]) -> "Graph":
+        """
+        Create a graph from multiple TriggerEdges (e.g., Trigger >> {NodeA, NodeB}).
+
+        Args:
+            edges: List of TriggerEdges
+
+        Returns:
+            Graph with all trigger edges and target nodes' ports as entrypoints/terminals
+        """
+        entrypoints: Set[Union["Port", NoPortsNode]] = set()
+        terminals: Set[Union["Port", NoPortsNode]] = set()
+
+        for edge in edges:
+            ports = {port for port in edge.to_node.Ports}
+            if not ports:
+                no_ports_node = NoPortsNode(edge.to_node)
+                entrypoints.add(no_ports_node)
+                terminals.add(no_ports_node)
+            else:
+                entrypoints.update(ports)
+                terminals.update(ports)
+
+        return Graph(
+            entrypoints=entrypoints,
+            edges=[],
+            terminals=terminals,
+            trigger_edges=edges,
+        )
+
     @staticmethod
     def empty() -> "Graph":
         """Create an empty graph with no entrypoints, edges, or terminals."""
         return Graph(entrypoints=set(), edges=[], terminals=set())
 
     def __rshift__(self, other: GraphTarget) -> "Graph":
+        # Check for trigger target (class-level only)
+        from vellum.workflows.triggers.base import BaseTrigger
+
+        if isinstance(other, type) and issubclass(other, BaseTrigger):
+            raise TypeError(
+                f"Cannot create edge targeting trigger {other.__name__}. "
+                f"Triggers must be at the start of a graph path, not as targets."
+            )
+
         if not self._edges and not self._entrypoints:
             raise ValueError("Graph instance can only create new edges from nodes within existing edges")
 
@@ -179,9 +251,30 @@ class Graph:
     def edges(self) -> Iterator[Edge]:
         return iter(self._edges)
 
+    @property
+    def trigger_edges(self) -> Iterator[TriggerEdge]:
+        """Get all trigger edges in this graph."""
+        return iter(self._trigger_edges)
+
+    @property
+    def triggers(self) -> Iterator[Type["BaseTrigger"]]:
+        """Get all unique trigger classes in this graph."""
+        seen_triggers = set()
+        for trigger_edge in self._trigger_edges:
+            if trigger_edge.trigger_class not in seen_triggers:
+                seen_triggers.add(trigger_edge.trigger_class)
+                yield trigger_edge.trigger_class
+
     @property
     def nodes(self) -> Iterator[Type["BaseNode"]]:
         nodes = set()
+
+        # Include nodes from trigger edges
+        for trigger_edge in self._trigger_edges:
+            if trigger_edge.to_node not in nodes:
+                nodes.add(trigger_edge.to_node)
+                yield trigger_edge.to_node
+
         if not self._edges:
             for node in self.entrypoints:
                 if node not in nodes:

vellum/workflows/graph/tests/test_graph.py

@@ -1,7 +1,10 @@
+import pytest
+
 from vellum.workflows.edges.edge import Edge
 from vellum.workflows.graph.graph import Graph
 from vellum.workflows.nodes.bases.base import BaseNode
 from vellum.workflows.ports.port import Port
+from vellum.workflows.triggers import ManualTrigger
 
 
 def test_graph__empty():
@@ -617,3 +620,167 @@ def test_graph__from_node_with_empty_ports():
 
     # THEN the graph should have exactly 1 node
     assert len(list(graph.nodes)) == 1
+
+
+def test_graph__manual_trigger_to_node():
+    # GIVEN a node
+    class MyNode(BaseNode):
+        pass
+
+    # WHEN we create graph with ManualTrigger >> Node (class-level, no instantiation)
+    graph = ManualTrigger >> MyNode
+
+    # THEN the graph has one trigger edge
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 1
+    assert trigger_edges[0].trigger_class == ManualTrigger
+    assert trigger_edges[0].to_node == MyNode
+
+    # AND the graph has one trigger
+    triggers = list(graph.triggers)
+    assert len(triggers) == 1
+    assert triggers[0] == ManualTrigger
+
+    # AND the graph has one node
+    assert len(list(graph.nodes)) == 1
+    assert MyNode in list(graph.nodes)
+
+
+def test_graph__manual_trigger_to_set_of_nodes():
+    # GIVEN two nodes
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    # WHEN we create graph with ManualTrigger >> {NodeA, NodeB}
+    graph = ManualTrigger >> {NodeA, NodeB}
+
+    # THEN the graph has two trigger edges
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 2
+
+    # AND both edges connect to the same ManualTrigger class
+    assert all(edge.trigger_class == ManualTrigger for edge in trigger_edges)
+
+    # AND edges connect to both nodes
+    target_nodes = {edge.to_node for edge in trigger_edges}
+    assert target_nodes == {NodeA, NodeB}
+
+    # AND the graph has one unique trigger
+    triggers = list(graph.triggers)
+    assert len(triggers) == 1
+
+    # AND the graph has two nodes
+    assert len(list(graph.nodes)) == 2
+
+
+def test_graph__manual_trigger_to_graph():
+    # GIVEN a graph of nodes
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    node_graph = NodeA >> NodeB
+
+    # WHEN we create graph with ManualTrigger >> Graph
+    graph = ManualTrigger >> node_graph
+
+    # THEN the graph has a trigger edge to the entrypoint
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 1
+    assert trigger_edges[0].to_node == NodeA
+
+    # AND the graph preserves the original edges
+    edges = list(graph.edges)
+    assert len(edges) == 1
+    assert edges[0].to_node == NodeB
+
+    # AND the graph has both nodes
+    nodes = list(graph.nodes)
+    assert len(nodes) == 2
+    assert NodeA in nodes
+    assert NodeB in nodes
+
+
+def test_graph__manual_trigger_to_set_of_graphs_preserves_edges():
+    # GIVEN two graphs of nodes
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    class NodeC(BaseNode):
+        pass
+
+    class NodeD(BaseNode):
+        pass
+
+    graph_one = NodeA >> NodeB
+    graph_two = NodeC >> NodeD
+
+    # WHEN we create a graph with ManualTrigger >> {Graph1, Graph2}
+    combined_graph = ManualTrigger >> {graph_one, graph_two}
+
+    # THEN the combined graph has trigger edges to both entrypoints
+    trigger_edges = list(combined_graph.trigger_edges)
+    assert len(trigger_edges) == 2
+    assert {edge.to_node for edge in trigger_edges} == {NodeA, NodeC}
+
+    # AND the combined graph preserves all downstream edges
+    edges = list(combined_graph.edges)
+    assert len(edges) == 2
+    assert {(edge.from_port.node_class, edge.to_node) for edge in edges} == {
+        (NodeA, NodeB),
+        (NodeC, NodeD),
+    }
+
+    # AND the combined graph still exposes all nodes
+    nodes = list(combined_graph.nodes)
+    assert {NodeA, NodeB, NodeC, NodeD}.issubset(nodes)
+
+
+def test_graph__node_to_trigger_raises():
+    # GIVEN a node and trigger
+    class MyNode(BaseNode):
+        pass
+
+    # WHEN we try to create Node >> Trigger (class-level)
+    # THEN it raises TypeError
+    with pytest.raises(TypeError, match="Cannot create edge targeting trigger"):
+        MyNode >> ManualTrigger
+
+    # WHEN we try to create Node >> Trigger (instance-level)
+    # THEN it also raises TypeError
+    with pytest.raises(TypeError, match="Cannot create edge targeting trigger"):
+        MyNode >> ManualTrigger
+
+
+def test_graph__trigger_then_graph_then_node():
+    # GIVEN a trigger, a node, and another node
+    class StartNode(BaseNode):
+        pass
+
+    class EndNode(BaseNode):
+        pass
+
+    # WHEN we create Trigger >> Node >> Node
+    graph = ManualTrigger >> StartNode >> EndNode
+
+    # THEN the graph has one trigger edge
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 1
+    assert trigger_edges[0].to_node == StartNode
+
+    # AND the graph has one regular edge
+    edges = list(graph.edges)
+    assert len(edges) == 1
+    assert edges[0].to_node == EndNode
+
+    # AND the graph has both nodes
+    nodes = list(graph.nodes)
+    assert len(nodes) == 2

vellum/workflows/nodes/displayable/subworkflow_deployment_node/node.py

@@ -21,7 +21,7 @@ from vellum.workflows.errors import WorkflowErrorCode
 from vellum.workflows.errors.types import workflow_event_error_to_workflow_error
 from vellum.workflows.events.types import default_serializer
 from vellum.workflows.events.workflow import is_workflow_event
-from vellum.workflows.exceptions import NodeException
+from vellum.workflows.exceptions import NodeException, WorkflowInitializationException
 from vellum.workflows.inputs.base import BaseInputs
 from vellum.workflows.nodes.bases.base import BaseNode
 from vellum.workflows.outputs.base import BaseOutput
@@ -164,6 +164,16 @@ class SubworkflowDeploymentNode(BaseNode[StateType], Generic[StateType]):
                 node_output_mocks=self._context._get_all_node_output_mocks(),
             )
 
+        try:
+            next(subworkflow_stream)
+        except WorkflowInitializationException as e:
+            hashed_module = e.definition.__module__
+            raise NodeException(
+                message=e.message,
+                code=e.code,
+                raw_data={"hashed_module": hashed_module},
+            ) from e
+
         outputs = None
         exception = None
         fulfilled_output_names: Set[str] = set()

vellum/workflows/nodes/displayable/tool_calling_node/node.py

@@ -47,7 +47,7 @@ class ToolCallingNode(BaseNode[StateType], Generic[StateType]):
     functions: ClassVar[List[Tool]] = []
     prompt_inputs: ClassVar[Optional[EntityInputsInterface]] = None
     parameters: PromptParameters = DEFAULT_PROMPT_PARAMETERS
-    max_prompt_iterations: ClassVar[Optional[int]] = 5
+    max_prompt_iterations: ClassVar[Optional[int]] = 25
     settings: ClassVar[Optional[Union[PromptSettings, Dict[str, Any]]]] = None
 
     class Outputs(BaseOutputs):

vellum/workflows/nodes/displayable/tool_calling_node/utils.py

@@ -89,7 +89,7 @@ class FunctionCallNodeMixin:
 
 
 class ToolPromptNode(InlinePromptNode[ToolCallingState]):
-    max_prompt_iterations: Optional[int] = 5
+    max_prompt_iterations: Optional[int] = 25
 
     class Trigger(InlinePromptNode.Trigger):
         merge_behavior = MergeBehavior.AWAIT_ATTRIBUTES

vellum/workflows/ports/port.py

@@ -61,6 +61,17 @@ class Port:
         return iter(self._edges)
 
     def __rshift__(self, other: GraphTarget) -> Graph:
+        # Check for trigger target (class-level only)
+        from vellum.workflows.triggers.base import BaseTrigger
+
+        # Check if other is a trigger class
+        if isinstance(other, type) and issubclass(other, BaseTrigger):
+            raise TypeError(
+                f"Cannot create edge targeting trigger {other.__name__}. "
+                f"Triggers must be at the start of a graph path, not as targets. "
+                f"Did you mean: {other.__name__} >> {self.node_class.__name__}?"
+            )
+
         if isinstance(other, set) or isinstance(other, Graph):
             return Graph.from_port(self) >> other
 

vellum/workflows/runner/runner.py

@@ -1,4 +1,5 @@
 from collections import defaultdict
+from contextlib import contextmanager
 from copy import deepcopy
 from dataclasses import dataclass
 import logging
@@ -73,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:
@@ -102,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,
@@ -232,7 +234,33 @@ class WorkflowRunner(Generic[StateType]):
 
         self._background_thread: Optional[Thread] = None
         self._cancel_thread: Optional[Thread] = None
-        self._stream_thread: Optional[Thread] = None
+
+    @contextmanager
+    def _httpx_logger_with_span_id(self) -> Iterator[None]:
+        """
+        Context manager to append the current execution's span ID to httpx logger messages.
+
+        This is used when making API requests via the Vellum client to include
+        the execution's span ID in the httpx request logs for better traceability.
+        """
+        httpx_logger = logging.getLogger("httpx")
+
+        class SpanIdFilter(logging.Filter):
+            def filter(self, record: logging.LogRecord) -> bool:
+                if record.name == "httpx" and "[span_id=" not in record.msg:
+                    context = get_execution_context()
+                    if context.parent_context:
+                        span_id = str(context.parent_context.span_id)
+                        record.msg = f"{record.msg} [span_id={span_id}]"
+                return True
+
+        span_filter = SpanIdFilter()
+        httpx_logger.addFilter(span_filter)
+
+        try:
+            yield
+        finally:
+            httpx_logger.removeFilter(span_filter)
 
     def _snapshot_state(self, state: StateType, deltas: List[StateDelta]) -> StateType:
         self._workflow_event_inner_queue.put(
@@ -707,6 +735,7 @@ class WorkflowRunner(Generic[StateType]):
             error_message: The error message to include in the cancellation events
             parent_context: The parent context for the cancellation events
         """
+        captured_stacktrace = "".join(traceback.format_stack())
         for span_id, active_node in list(self._active_nodes_by_execution_id.items()):
             rejection_event = NodeExecutionRejectedEvent(
                 trace_id=self._execution_context.trace_id,
@@ -717,6 +746,7 @@ class WorkflowRunner(Generic[StateType]):
                         code=WorkflowErrorCode.NODE_CANCELLED,
                         message=error_message,
                     ),
+                    stacktrace=captured_stacktrace,
                 ),
                 parent=parent_context,
             )
@@ -770,13 +800,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,
         )
@@ -824,6 +855,11 @@ class WorkflowRunner(Generic[StateType]):
             parent=self._execution_context.parent_context,
         )
 
+    def _wrapped_stream(self) -> None:
+        """Wrapper for _stream that adds httpx logger span ID context."""
+        with self._httpx_logger_with_span_id():
+            self._stream()
+
     def _stream(self) -> None:
         for edge in self.workflow.get_edges():
             self._dependencies[edge.to_node].add(edge.from_port.node_class)
@@ -927,7 +963,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()
@@ -960,12 +996,14 @@ class WorkflowRunner(Generic[StateType]):
                     parent_context=parent_context,
                 )
 
+                captured_stacktrace = "".join(traceback.format_stack())
                 self._workflow_event_outer_queue.put(
                     self._reject_workflow_event(
                         WorkflowError(
                             code=WorkflowErrorCode.WORKFLOW_CANCELLED,
                             message="Workflow run cancelled",
-                        )
+                        ),
+                        captured_stacktrace,
                     )
                 )
                 return
@@ -1005,7 +1043,7 @@ class WorkflowRunner(Generic[StateType]):
 
         # The extra level of indirection prevents the runner from waiting on the caller to consume the event stream
         self._stream_thread = Thread(
-            target=self._stream,
+            target=self._wrapped_stream,
             name=f"{self.workflow.__class__.__name__}.stream_thread",
         )
         self._stream_thread.start()

vellum/workflows/triggers/__init__.py

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