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

vellum/workflows/references/state_value.py

@@ -1,8 +1,11 @@
-from typing import TYPE_CHECKING, TypeVar, cast
+from functools import cached_property
+from uuid import UUID
+from typing import TYPE_CHECKING, Optional, Tuple, Type, TypeVar, cast
 
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.errors.types import WorkflowErrorCode
 from vellum.workflows.exceptions import NodeException
+from vellum.workflows.utils.uuids import get_state_value_id
 
 if TYPE_CHECKING:
     from vellum.workflows.state.base import BaseState
@@ -13,6 +16,26 @@ _T = TypeVar("_T")
 
 class StateValueReference(BaseDescriptor[_T]):
 
+    def __init__(
+        self,
+        *,
+        name: str,
+        types: Tuple[Type[_T], ...],
+        instance: Optional[_T],
+        state_class: Type["BaseState"],
+    ) -> None:
+        super().__init__(name=name, types=types, instance=instance)
+        self._state_class = state_class
+
+    @property
+    def state_class(self) -> Type["BaseState"]:
+        return self._state_class
+
+    @cached_property
+    def id(self) -> UUID:
+        """Generate deterministic UUID from state class and state value name."""
+        return get_state_value_id(self._state_class, self.name)
+
     def resolve(self, state: "BaseState") -> _T:
         if hasattr(state, self._name):
             return cast(_T, getattr(state, self._name))

vellum/workflows/references/tests/test_lazy.py

@@ -1,9 +1,29 @@
 import pytest
 
+from vellum.workflows import BaseWorkflow
 from vellum.workflows.nodes import BaseNode
 from vellum.workflows.references.lazy import LazyReference
 
 
+class ResponseNode(BaseNode):
+    class Outputs(BaseNode.Outputs):
+        response: str = "Hello from node!"
+
+
+class TestWorkflowWithOutput(BaseWorkflow):
+    graph = ResponseNode
+
+    class Outputs(BaseWorkflow.Outputs):
+        final_response = ResponseNode.Outputs.response
+
+
+class TestWorkflowWithLiteralOutput(BaseWorkflow):
+    graph = ResponseNode
+
+    class Outputs(BaseWorkflow.Outputs):
+        literal_value = "Hello literal!"
+
+
 @pytest.fixture
 def mock_inspect_getsource(mocker):
     return mocker.patch("inspect.getsource")
@@ -28,3 +48,41 @@ def test_lazy_reference__inspect_getsource_fails(mock_inspect_getsource, mock_lo
 
     # AND sentry is notified
     assert mock_logger.exception.call_count == 1
+
+
+def test_lazy_reference__string_resolves_workflow_output():
+    """Tests that string-based LazyReference can resolve workflow output references."""
+
+    # GIVEN a workflow with an output that references a node output (defined at module level)
+    # WHEN we run the workflow
+    terminal_event = TestWorkflowWithOutput().run()
+
+    # THEN the workflow completes successfully
+    assert terminal_event.name == "workflow.execution.fulfilled"
+    assert terminal_event.final_state is not None
+
+    # AND we can resolve a string-based LazyReference to the workflow output
+    lazy_ref = LazyReference[str]("TestWorkflowWithOutput.Outputs.final_response")
+    resolved_value = lazy_ref.resolve(terminal_event.final_state)
+
+    # THEN the resolved value matches the node output
+    assert resolved_value == "Hello from node!"
+
+
+def test_lazy_reference__string_resolves_literal_workflow_output():
+    """Tests that string-based LazyReference can resolve literal workflow output values."""
+
+    # GIVEN a workflow with a literal output value (defined at module level)
+    # WHEN we run the workflow
+    terminal_event = TestWorkflowWithLiteralOutput().run()
+
+    # THEN the workflow completes successfully
+    assert terminal_event.name == "workflow.execution.fulfilled"
+    assert terminal_event.final_state is not None
+
+    # AND we can resolve a string-based LazyReference to the literal workflow output
+    lazy_ref = LazyReference[str]("TestWorkflowWithLiteralOutput.Outputs.literal_value")
+    resolved_value = lazy_ref.resolve(terminal_event.final_state)
+
+    # THEN the resolved value matches the literal output
+    assert resolved_value == "Hello literal!"

vellum/workflows/references/trigger.py

@@ -11,7 +11,6 @@ from pydantic_core import core_schema
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.errors.types import WorkflowErrorCode
 from vellum.workflows.exceptions import NodeException
-from vellum.workflows.utils.uuids import get_trigger_attribute_id
 
 if TYPE_CHECKING:
     from vellum.workflows.state.base import BaseState
@@ -40,8 +39,14 @@ class TriggerAttributeReference(BaseDescriptor[_T], Generic[_T]):
 
     @property
     def id(self) -> UUID:
-        """Generate deterministic UUID from trigger class qualname and attribute name."""
-        return get_trigger_attribute_id(self._trigger_class, self.name)
+        """
+        Get the trigger attribute ID via the trigger class, which knows how to read
+        metadata.json and fall back to hash-based IDs.
+
+        This ensures trigger attribute IDs remain stable across serialization round-trips
+        when metadata.json is present.
+        """
+        return self._trigger_class.get_attribute_id(self.name)
 
     def resolve(self, state: BaseState) -> _T:
         trigger_attributes = getattr(state.meta, "trigger_attributes", {})

vellum/workflows/references/workflow_input.py

@@ -1,9 +1,12 @@
+from functools import cached_property
+from uuid import UUID
 from typing import TYPE_CHECKING, Generic, Optional, Tuple, Type, TypeVar, cast
 
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.errors.types import WorkflowErrorCode
 from vellum.workflows.exceptions import NodeException
 from vellum.workflows.types.generics import import_workflow_class
+from vellum.workflows.utils.uuids import get_workflow_input_id
 
 if TYPE_CHECKING:
     from vellum.workflows.inputs.base import BaseInputs
@@ -29,6 +32,11 @@ class WorkflowInputReference(BaseDescriptor[_InputType], Generic[_InputType]):
     def inputs_class(self) -> Type["BaseInputs"]:
         return self._inputs_class
 
+    @cached_property
+    def id(self) -> UUID:
+        """Generate deterministic UUID from inputs class and input name."""
+        return get_workflow_input_id(self._inputs_class, self.name)
+
     def resolve(self, state: "BaseState") -> _InputType:
         if hasattr(state.meta.workflow_inputs, self._name) and (
             state.meta.workflow_definition == self._inputs_class.__parent_class__

vellum/workflows/resolvers/resolver.py

@@ -2,6 +2,7 @@ import logging
 from uuid import UUID
 from typing import Iterator, Optional, Type, Union
 
+from vellum.client.core.api_error import ApiError
 from vellum.workflows.events.workflow import WorkflowEvent
 from vellum.workflows.nodes.utils import cast_to_output_type
 from vellum.workflows.resolvers.base import BaseWorkflowResolver
@@ -45,9 +46,18 @@ class VellumResolver(BaseWorkflowResolver):
             return None
 
         client = self._context.vellum_client
-        response = client.workflows.retrieve_state(
-            span_id=previous_execution_id,
-        )
+        try:
+            response = client.workflows.retrieve_state(
+                span_id=previous_execution_id,
+            )
+        except ApiError as e:
+            if e.status_code == 404:
+                logger.debug(
+                    "No state found for previous execution %s, continuing without previous state",
+                    previous_execution_id,
+                )
+                return None
+            raise
 
         if response.state is None:
             return None

vellum/workflows/resolvers/tests/test_resolver.py

@@ -4,6 +4,7 @@ from uuid import uuid4
 from typing import List
 
 from vellum import ChatMessage
+from vellum.client.core.api_error import ApiError
 from vellum.client.types.workflow_resolved_state import WorkflowResolvedState
 from vellum.workflows import BaseWorkflow
 from vellum.workflows.inputs.base import BaseInputs
@@ -166,3 +167,33 @@ def test_load_state_with_chat_message_list():
     assert result.state.chat_history[2].text == "What can you help me with?"
 
     mock_client.workflows.retrieve_state.assert_called_once_with(span_id=str(execution_id))
+
+
+def test_load_state_returns_none_on_404():
+    """Test load_state returns None when retrieve_state returns 404 (e.g., rejected execution with no state)."""
+    resolver = VellumResolver()
+    execution_id = uuid4()
+
+    class TestState(BaseState):
+        test_key: str = "test_value"
+
+    class TestWorkflow(BaseWorkflow[BaseInputs, TestState]):
+        pass
+
+    # GIVEN a mock client that raises ApiError with 404 status
+    mock_client = Mock()
+    mock_client.workflows.retrieve_state.side_effect = ApiError(
+        status_code=404,
+        body={"detail": "No state found for the given span_id"},
+    )
+
+    # AND context with the test workflow class is set up
+    context = WorkflowContext(vellum_client=mock_client)
+    TestWorkflow(context=context, resolvers=[resolver])
+
+    # WHEN load_state is called with an execution ID that has no state
+    result = resolver.load_state(previous_execution_id=execution_id)
+
+    # THEN should return None instead of raising an exception
+    assert result is None
+    mock_client.workflows.retrieve_state.assert_called_once_with(span_id=str(execution_id))

vellum/workflows/runner/runner.py

@@ -25,6 +25,7 @@ from typing import (
     Union,
 )
 
+from vellum.client.core.api_error import ApiError
 from vellum.workflows.constants import undefined
 from vellum.workflows.context import ExecutionContext, execution_context, get_execution_context
 from vellum.workflows.descriptors.base import BaseDescriptor
@@ -49,7 +50,14 @@ from vellum.workflows.events.node import (
     NodeExecutionRejectedBody,
     NodeExecutionStreamingBody,
 )
-from vellum.workflows.events.types import BaseEvent, NodeParentContext, ParentContext, SpanLink, WorkflowParentContext
+from vellum.workflows.events.types import (
+    BaseEvent,
+    NodeParentContext,
+    ParentContext,
+    SpanLink,
+    WorkflowParentContext,
+    default_serializer,
+)
 from vellum.workflows.events.workflow import (
     WorkflowEventStream,
     WorkflowExecutionFulfilledBody,
@@ -64,6 +72,7 @@ from vellum.workflows.events.workflow import (
     WorkflowExecutionStreamingBody,
 )
 from vellum.workflows.exceptions import NodeException, WorkflowInitializationException
+from vellum.workflows.inputs.base import BaseInputs
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.nodes.bases.base import NodeRunResponse
 from vellum.workflows.nodes.mocks import MockNodeExecutionArg
@@ -114,6 +123,7 @@ class WorkflowRunner(Generic[StateType]):
         init_execution_context: Optional[ExecutionContext] = None,
         trigger: Optional[BaseTrigger] = None,
         execution_id: Optional[UUID] = None,
+        event_max_size: Optional[int] = None,
     ):
         if state and external_inputs:
             raise ValueError("Can only run a Workflow providing one of state or external inputs, not both")
@@ -200,23 +210,28 @@ class WorkflowRunner(Generic[StateType]):
                     continue
 
             if resolver_failed:
-                raise WorkflowInitializationException(
-                    message=f"All resolvers failed to load initial state for execution ID: {previous_execution_id}",
-                    workflow_definition=self.workflow.__class__,
-                    code=WorkflowErrorCode.INVALID_INPUTS,
+                logger.warning(
+                    f"All resolvers failed to load initial state for execution ID: {previous_execution_id}. "
+                    "Falling back to default state."
                 )
+                normalized_inputs = deepcopy(inputs) if inputs else self.workflow.get_default_inputs()
+                self._initial_state = self.workflow.get_default_state(normalized_inputs, execution_id)
 
             self._entrypoints = self.workflow.get_entrypoints()
         elif trigger:
             # When trigger is provided, set up default state and filter entrypoints by trigger type
-            normalized_inputs = deepcopy(inputs) if inputs else self.workflow.get_default_inputs()
+            default_inputs = deepcopy(inputs) if inputs else None
             if state:
                 self._initial_state = deepcopy(state)
-                self._initial_state.meta.workflow_inputs = normalized_inputs
+                self._initial_state.meta.workflow_inputs = default_inputs
                 self._initial_state.meta.span_id = execution_id or uuid4()
                 self._initial_state.meta.workflow_definition = self.workflow.__class__
             else:
-                self._initial_state = self.workflow.get_default_state(normalized_inputs, execution_id)
+                self._initial_state = self.workflow.get_default_state(
+                    default_inputs,
+                    execution_id,
+                    trigger_attributes={},
+                )
                 self._should_emit_initial_state = False
 
             # Validate and bind trigger, then filter entrypoints
@@ -263,6 +278,7 @@ class WorkflowRunner(Generic[StateType]):
         self._timeout = timeout
         self._execution_context = init_execution_context or get_execution_context()
         self._trigger = trigger
+        self._event_max_size = event_max_size
 
         setattr(
             self._initial_state,
@@ -271,6 +287,7 @@ class WorkflowRunner(Generic[StateType]):
         )
         self.workflow.context._register_event_queue(self._workflow_event_inner_queue)
         self.workflow.context._register_node_output_mocks(node_output_mocks or [])
+        self.workflow.context._register_event_max_size(event_max_size)
 
         self._outputs_listening_to_state = [
             descriptor for descriptor in self.workflow.Outputs if isinstance(descriptor.instance, StateValueReference)
@@ -294,13 +311,17 @@ class WorkflowRunner(Generic[StateType]):
         Allows subclasses: if trigger_class is a subclass of any declared trigger,
         returns those entrypoints.
         """
+        seen: Set[Type[BaseNode]] = set()
         entrypoints: List[Type[BaseNode]] = []
         for subgraph in self.workflow.get_subgraphs():
             for trigger in subgraph.triggers:
                 # Check if the provided trigger_class is a subclass of the declared trigger
                 # This allows runtime instances to be subclasses of what's declared in the workflow
                 if issubclass(trigger_class, trigger):
-                    entrypoints.extend(subgraph.entrypoints)
+                    for entrypoint in subgraph.entrypoints:
+                        if entrypoint not in seen:
+                            seen.add(entrypoint)
+                            entrypoints.append(entrypoint)
         return entrypoints
 
     def _validate_and_bind_trigger(self, trigger: BaseTrigger) -> None:
@@ -461,6 +482,8 @@ class WorkflowRunner(Generic[StateType]):
         return state
 
     def _emit_event(self, event: WorkflowEvent) -> WorkflowEvent:
+        if self._event_max_size is not None:
+            event._event_max_size = self._event_max_size
         self.workflow._store.append_event(event)
         self._background_thread_queue.put(event)
         return event
@@ -510,6 +533,8 @@ class WorkflowRunner(Generic[StateType]):
             was_mocked: Optional[bool] = None
             mock_candidates = node_output_mocks_map.get(node.Outputs) or []
             for mock_candidate in mock_candidates:
+                if mock_candidate.disabled:
+                    continue
                 if mock_candidate.when_condition.resolve(node.state):
                     node_run_response = mock_candidate.then_outputs
                     was_mocked = True
@@ -565,6 +590,16 @@ class WorkflowRunner(Generic[StateType]):
 
                 with execution_context(parent_context=updated_parent_context, trace_id=execution.trace_id):
                     for output in node_run_response:
+                        try:
+                            default_serializer(output)
+                        except (TypeError, ValueError) as exc:
+                            raise NodeException(
+                                message=(
+                                    f"Node {node.__class__.__name__} produced output: "
+                                    f"'{output.name}' that could not be serialized to JSON: {exc}"
+                                ),
+                                code=WorkflowErrorCode.INVALID_OUTPUTS,
+                            ) from exc
                         invoked_ports = output > ports
                         if output.is_initiated:
                             yield from initiate_node_streaming_output(output)
@@ -599,6 +634,20 @@ class WorkflowRunner(Generic[StateType]):
                                 parent=execution.parent_context,
                             )
 
+            for descriptor, output_value in outputs:
+                if output_value is undefined:
+                    continue
+                try:
+                    default_serializer(output_value)
+                except (TypeError, ValueError) as exc:
+                    raise NodeException(
+                        message=(
+                            f"Node {node.__class__.__name__} produced output '{descriptor.name}' "
+                            f"that could not be serialized to JSON: {exc}"
+                        ),
+                        code=WorkflowErrorCode.INVALID_OUTPUTS,
+                    ) from exc
+
             node.state.meta.node_execution_cache.fulfill_node_execution(node.__class__, span_id)
 
             with execution_context(parent_context=updated_parent_context, trace_id=execution.trace_id):
@@ -610,7 +659,15 @@ class WorkflowRunner(Generic[StateType]):
                             continue
                         node.state.meta.node_outputs[descriptor] = output_value
 
-            invoked_ports = ports(outputs, node.state)
+            try:
+                invoked_ports = ports(outputs, node.state)
+            except NodeException as e:
+                raise NodeException(
+                    message=e.message,
+                    code=e.code,
+                    raw_data={**(e.raw_data or {}), "outputs": outputs.__vellum_encode__()},
+                    stacktrace=e.stacktrace,
+                ) from e
             yield NodeExecutionFulfilledEvent(
                 trace_id=execution.trace_id,
                 span_id=span_id,
@@ -628,6 +685,71 @@ class WorkflowRunner(Generic[StateType]):
             yield self._handle_run_node_exception(e, "Workflow Initialization Exception", execution, span_id, node)
         except InvalidExpressionException as e:
             yield self._handle_run_node_exception(e, "Invalid Expression Exception", execution, span_id, node)
+        except ApiError as e:
+            captured_stacktrace = traceback.format_exc()
+            # Handle structured 403 credential error responses with integration details
+            # The Django API returns {"message": "...", "integration": {...}} for unresolvable credentials
+            # We detect this by shape (403 + integration field present) rather than a code field
+            if e.status_code == 403 and isinstance(e.body, dict) and e.body.get("integration"):
+                error_message = e.body.get(
+                    "message", "You must authenticate with this integration before you can execute this tool."
+                )
+                raw_data = {"integration": e.body["integration"]}
+                yield NodeExecutionRejectedEvent(
+                    trace_id=execution.trace_id,
+                    span_id=span_id,
+                    body=NodeExecutionRejectedBody(
+                        node_definition=node.__class__,
+                        error=WorkflowError(
+                            message=error_message,
+                            code=WorkflowErrorCode.INTEGRATION_CREDENTIALS_UNAVAILABLE,
+                            raw_data=raw_data,
+                        ),
+                        stacktrace=captured_stacktrace,
+                    ),
+                    parent=execution.parent_context,
+                )
+            # Handle structured 400 error responses with integration details as INVALID_INPUTS
+            elif e.status_code == 400 and isinstance(e.body, dict) and e.body.get("integration"):
+                error_message = e.body.get("message", "Invalid request to integration.")
+                raw_data = {"integration": e.body["integration"]}
+                yield NodeExecutionRejectedEvent(
+                    trace_id=execution.trace_id,
+                    span_id=span_id,
+                    body=NodeExecutionRejectedBody(
+                        node_definition=node.__class__,
+                        error=WorkflowError(
+                            message=error_message,
+                            code=WorkflowErrorCode.INVALID_INPUTS,
+                            raw_data=raw_data,
+                        ),
+                        stacktrace=captured_stacktrace,
+                    ),
+                    parent=execution.parent_context,
+                )
+            else:
+                # For all other ApiErrors, use the existing generic exception behavior
+                error_message = self._parse_error_message(e)
+                if error_message is None:
+                    logger.exception(f"An unexpected error occurred while running node {node.__class__.__name__}")
+                    error_code = WorkflowErrorCode.INTERNAL_ERROR
+                    error_message = "Internal error"
+                else:
+                    error_code = WorkflowErrorCode.NODE_EXECUTION
+
+                yield NodeExecutionRejectedEvent(
+                    trace_id=execution.trace_id,
+                    span_id=span_id,
+                    body=NodeExecutionRejectedBody(
+                        node_definition=node.__class__,
+                        error=WorkflowError(
+                            message=error_message,
+                            code=error_code,
+                        ),
+                        stacktrace=captured_stacktrace,
+                    ),
+                    parent=execution.parent_context,
+                )
         except Exception as e:
             error_message = self._parse_error_message(e)
             captured_stacktrace = traceback.format_exc()
@@ -817,7 +939,7 @@ class WorkflowRunner(Generic[StateType]):
                             )
                         )
                     )
-                    return None
+                    continue
 
                 node_output_descriptor = workflow_output_descriptor.instance
                 if not isinstance(node_output_descriptor, OutputReference):
@@ -931,14 +1053,19 @@ class WorkflowRunner(Generic[StateType]):
                 ),
             ]
 
+        # Get raw inputs from trigger event data if available
+        # This ensures trigger attributes are included in the serialized inputs
+        raw_inputs = self._trigger._event_data if self._trigger else None
+
         return WorkflowExecutionInitiatedEvent(
             trace_id=self._execution_context.trace_id,
             span_id=self._initial_state.meta.span_id,
             body=WorkflowExecutionInitiatedBody(
                 workflow_definition=self.workflow.__class__,
-                inputs=self._initial_state.meta.workflow_inputs,
+                inputs=self._initial_state.meta.workflow_inputs or BaseInputs(),
                 initial_state=deepcopy(self._initial_state) if self._should_emit_initial_state else None,
                 trigger=self._trigger.__class__ if self._trigger else None,
+                raw_inputs=raw_inputs,
             ),
             parent=self._execution_context.parent_context,
             links=links,
@@ -1019,6 +1146,10 @@ class WorkflowRunner(Generic[StateType]):
         for edge in self.workflow.get_edges():
             self._dependencies[edge.to_node].add(edge.from_port.node_class)
 
+        # Call trigger initiated hook so nodes can reference trigger state
+        if self._trigger is not None:
+            self._trigger.__on_workflow_initiated__(self._initial_state)
+
         current_parent = WorkflowParentContext(
             span_id=self._initial_state.meta.span_id,
             workflow_definition=self.workflow.__class__,
@@ -1078,9 +1209,11 @@ class WorkflowRunner(Generic[StateType]):
                 self._workflow_event_outer_queue.put(event)
 
                 with execution_context(parent_context=current_parent, trace_id=self._execution_context.trace_id):
-                    rejection_event = self._handle_work_item_event(event)
+                    new_rejection_event = self._handle_work_item_event(event)
 
-                if rejection_event:
+                if new_rejection_event:
+                    if rejection_event is None:
+                        rejection_event = new_rejection_event
                     break
         except Empty:
             pass
@@ -1106,6 +1239,18 @@ class WorkflowRunner(Generic[StateType]):
             )
             return
 
+        # Call trigger fulfilled hook before output resolution so state changes are reflected in outputs
+        if self._trigger is not None:
+            self._trigger.__on_workflow_fulfilled__(final_state)
+
+            # Drain any events produced by the trigger hook (e.g., snapshot events from state mutations)
+            # and forward them to the outer queue so stream consumers can observe them
+            try:
+                while event := self._workflow_event_inner_queue.get_nowait():
+                    self._workflow_event_outer_queue.put(event)
+            except Empty:
+                pass
+
         fulfilled_outputs = self.workflow.Outputs()
         for descriptor, value in fulfilled_outputs:
             if isinstance(value, BaseDescriptor):