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

vellum/client/core/client_wrapper.py

@@ -27,10 +27,10 @@ class BaseClientWrapper:
 
     def get_headers(self) -> typing.Dict[str, str]:
         headers: typing.Dict[str, str] = {
-            "User-Agent": "vellum-ai/1.7.5",
+            "User-Agent": "vellum-ai/1.7.7",
             "X-Fern-Language": "Python",
             "X-Fern-SDK-Name": "vellum-ai",
-            "X-Fern-SDK-Version": "1.7.5",
+            "X-Fern-SDK-Version": "1.7.7",
             **(self.get_custom_headers() or {}),
         }
         if self._api_version is not None:

vellum/workflows/nodes/bases/base.py

@@ -1,10 +1,26 @@
 from abc import ABC, ABCMeta, abstractmethod
+from collections.abc import Callable as CollectionsCallable
 from dataclasses import field
 from functools import cached_property, reduce
 import inspect
 from types import MappingProxyType
 from uuid import UUID, uuid4
-from typing import Any, Dict, Generic, Iterator, Optional, Set, Tuple, Type, TypeVar, Union, cast, get_args
+from typing import (
+    Any,
+    Callable as TypingCallable,
+    Dict,
+    Generic,
+    Iterator,
+    Optional,
+    Set,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+)
 
 from vellum.workflows.constants import undefined
 from vellum.workflows.descriptors.base import BaseDescriptor
@@ -43,15 +59,15 @@ def _is_nested_class(nested: Any, parent: Type) -> bool:
     ) or any(_is_nested_class(nested, base) for base in parent.__bases__)
 
 
-def _is_annotated(cls: Type, name: str) -> bool:
+def _is_annotated(cls: Type, name: str) -> Any:
     if name in cls.__annotations__:
-        return True
+        return cls.__annotations__[name]
 
     for base in cls.__bases__:
-        if _is_annotated(base, name):
-            return True
+        if annotation := _is_annotated(base, name):
+            return annotation
 
-    return False
+    return None
 
 
 class BaseNodeMeta(ABCMeta):
@@ -151,8 +167,10 @@ class BaseNodeMeta(ABCMeta):
         try:
             attribute = super().__getattribute__(name)
         except AttributeError as e:
-            if _is_annotated(cls, name):
-                attribute = None
+            annotation = _is_annotated(cls, name)
+            origin_annotation = get_origin(annotation)
+            if origin_annotation is not CollectionsCallable and origin_annotation is not TypingCallable:
+                attribute = undefined
             else:
                 raise e
 
@@ -482,7 +500,8 @@ class BaseNode(Generic[StateType], ABC, BaseExecutable, metaclass=BaseNodeMeta):
                     setattr(base, leaf, input_value)
 
         for descriptor in self.__class__:
-            if not descriptor.instance:
+            if descriptor.instance is undefined:
+                setattr(self, descriptor.name, undefined)
                 continue
 
             if any(isinstance(t, type) and issubclass(t, BaseDescriptor) for t in descriptor.types):

vellum/workflows/nodes/bases/base_adornment_node.py

@@ -1,10 +1,12 @@
 from abc import ABC
-from typing import TYPE_CHECKING, Any, Dict, Generic, Optional, Tuple, Type
+from uuid import UUID
+from typing import TYPE_CHECKING, Any, Dict, Generic, Optional, Set, Tuple, Type
 
 from vellum.workflows.inputs.base import BaseInputs
 from vellum.workflows.nodes.bases.base import BaseNode, BaseNodeMeta
 from vellum.workflows.outputs.base import BaseOutputs
 from vellum.workflows.references.output import OutputReference
+from vellum.workflows.types.core import MergeBehavior
 from vellum.workflows.types.generics import StateType
 
 if TYPE_CHECKING:
@@ -79,6 +81,56 @@ class BaseAdornmentNode(
     __wrapped_node__: Optional[Type["BaseNode"]] = None
     subworkflow: Type["BaseWorkflow"]
 
+    class Trigger(BaseNode.Trigger):
+        """
+        Trigger class for adornment nodes that delegates to the wrapped node's Trigger
+        for proper merge behavior handling.
+        """
+
+        @classmethod
+        def should_initiate(
+            cls,
+            state: StateType,
+            dependencies: Set["Type[BaseNode]"],
+            node_span_id: UUID,
+        ) -> bool:
+            """
+            Delegates to the wrapped node's Trigger.should_initiate method to ensure
+            proper merge behavior (like AWAIT_ALL) is respected for initiation logic.
+            """
+            # Get the wrapped node's Trigger class
+            wrapped_node = cls.node_class.__wrapped_node__
+            if wrapped_node is not None:
+                wrapped_trigger = wrapped_node.Trigger
+                # Only delegate if the wrapped node has a specific merge behavior
+                # that differs from the default AWAIT_ATTRIBUTES
+                if (
+                    hasattr(wrapped_trigger, "merge_behavior")
+                    and wrapped_trigger.merge_behavior != MergeBehavior.AWAIT_ATTRIBUTES
+                ):
+                    return wrapped_trigger.should_initiate(state, dependencies, node_span_id)
+
+            # Fallback to the base implementation if no wrapped node
+            return super().should_initiate(state, dependencies, node_span_id)
+
+        @classmethod
+        def _queue_node_execution(
+            cls, state: StateType, dependencies: set[Type[BaseNode]], invoked_by: Optional[UUID] = None
+        ) -> UUID:
+            """
+            Delegates to the wrapped node's Trigger._queue_node_execution method to ensure
+            proper merge behavior (like AWAIT_ALL) is respected for dependency tracking.
+            """
+            # Get the wrapped node's Trigger class
+            wrapped_node = cls.node_class.__wrapped_node__
+            if wrapped_node is not None:
+                wrapped_trigger = wrapped_node.Trigger
+                # Delegate to the wrapped node's trigger logic for queuing
+                return wrapped_trigger._queue_node_execution(state, dependencies, invoked_by)
+
+            # Fallback to the base implementation if no wrapped node
+            return super()._queue_node_execution(state, dependencies, invoked_by)
+
     @classmethod
     def __annotate_outputs_class__(cls, outputs_class: Type[BaseOutputs], reference: OutputReference) -> None:
         # Subclasses of BaseAdornableNode can override this method to provider their own

vellum/workflows/nodes/displayable/bases/inline_prompt_node/node.py

@@ -7,6 +7,7 @@ from vellum import (
     AdHocExpandMeta,
     ChatMessage,
     FunctionDefinition,
+    InitiatedAdHocExecutePromptEvent,
     PromptBlock,
     PromptOutput,
     PromptParameters,
@@ -185,7 +186,8 @@ class BaseInlinePromptNode(BasePromptNode[StateType], Generic[StateType]):
                 expand_meta=self.expand_meta,
                 request_options=request_options,
             )
-            return iter([response])
+            initiated_event = InitiatedAdHocExecutePromptEvent(execution_id=response.execution_id)
+            return iter([initiated_event, response])
         else:
             return self._context.vellum_client.ad_hoc.adhoc_execute_prompt_stream(
                 ml_model=self.ml_model,

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

@@ -1,6 +1,7 @@
 import json
 from typing import ClassVar
 
+from vellum.workflows.constants import undefined
 from vellum.workflows.errors import WorkflowErrorCode
 from vellum.workflows.exceptions import NodeException
 from vellum.workflows.nodes.displayable.bases import BaseSearchNode as BaseSearchNode
@@ -37,7 +38,7 @@ class SearchNode(BaseSearchNode[StateType]):
         text: str
 
     def run(self) -> Outputs:
-        if self.query is None or self.query == "":
+        if self.query is undefined or self.query is None or self.query == "":
             raise NodeException(
                 message="Search query is required but was not provided",
                 code=WorkflowErrorCode.INVALID_INPUTS,

vellum/workflows/nodes/displayable/search_node/tests/test_node.py

@@ -234,3 +234,17 @@ def test_run_workflow__invalid_query_raises_validation_error(invalid_query):
     assert exc_info.value.code == WorkflowErrorCode.INVALID_INPUTS
     assert "query" in exc_info.value.message.lower()
     assert "required" in exc_info.value.message.lower() or "missing" in exc_info.value.message.lower()
+
+
+def test_run_workflow__missing_query_attribute_raises_validation_error():
+    """Confirm that a SearchNode without a query attribute defined raises INVALID_INPUTS"""
+
+    class MySearchNode(SearchNode):
+        document_index = "document_index"
+
+    with pytest.raises(NodeException) as exc_info:
+        MySearchNode().run()
+
+    assert exc_info.value.code == WorkflowErrorCode.INVALID_INPUTS
+    assert "query" in exc_info.value.message.lower()
+    assert "required" in exc_info.value.message.lower()

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

@@ -15,7 +15,7 @@ from vellum import (
 from vellum.client.core import RequestOptions
 from vellum.client.core.api_error import ApiError
 from vellum.client.types.chat_message_request import ChatMessageRequest
-from vellum.workflows.constants import LATEST_RELEASE_TAG, OMIT
+from vellum.workflows.constants import LATEST_RELEASE_TAG, OMIT, undefined
 from vellum.workflows.context import execution_context, get_execution_context, get_parent_context
 from vellum.workflows.errors import WorkflowErrorCode
 from vellum.workflows.errors.types import workflow_event_error_to_workflow_error
@@ -226,6 +226,12 @@ class SubworkflowDeploymentNode(BaseNode[StateType], Generic[StateType]):
             **request_options.get("additional_body_parameters", {}),
         }
 
+        if self.deployment is undefined:
+            raise NodeException(
+                code=WorkflowErrorCode.NODE_EXECUTION,
+                message="Expected subworkflow deployment attribute to be either a UUID or STR, got `undefined` instead",
+            )
+
         try:
             deployment_id = str(self.deployment) if isinstance(self.deployment, UUID) else None
             deployment_name = self.deployment if isinstance(self.deployment, str) else None

vellum/workflows/nodes/displayable/subworkflow_deployment_node/tests/test_node.py

@@ -265,7 +265,7 @@ def test_run_workflow__no_deployment():
 
     # AND the error message should be correct
     assert exc_info.value.code == WorkflowErrorCode.NODE_EXECUTION
-    assert "Expected subworkflow deployment attribute to be either a UUID or STR, got None instead" in str(
+    assert "Expected subworkflow deployment attribute to be either a UUID or STR, got `undefined` instead" in str(
         exc_info.value
     )
 

vellum/workflows/nodes/displayable/tool_calling_node/tests/test_node.py

@@ -1,3 +1,4 @@
+import pytest
 import json
 from uuid import uuid4
 from typing import Any, Iterator, List
@@ -14,6 +15,8 @@ from vellum.client.types.string_vellum_value import StringVellumValue
 from vellum.client.types.variable_prompt_block import VariablePromptBlock
 from vellum.prompts.constants import DEFAULT_PROMPT_PARAMETERS
 from vellum.workflows import BaseWorkflow
+from vellum.workflows.errors.types import WorkflowErrorCode
+from vellum.workflows.exceptions import NodeException
 from vellum.workflows.inputs.base import BaseInputs
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.nodes.displayable.tool_calling_node.node import ToolCallingNode
@@ -372,3 +375,54 @@ def test_tool_calling_node_workflow_is_dynamic(vellum_adhoc_prompt_client):
     assert initiated_events[0].body.workflow_definition.is_dynamic is False  # Main workflow
     assert initiated_events[1].body.workflow_definition.is_dynamic is True  # Tool calling internal
     assert initiated_events[2].body.workflow_definition.is_dynamic is True  # Inline workflow
+
+
+def test_tool_node_preserves_node_exception():
+    """Test that tool nodes preserve NodeException error codes and raw_data."""
+
+    def failing_function() -> str:
+        raise NodeException(
+            message="Custom error",
+            code=WorkflowErrorCode.INVALID_INPUTS,
+            raw_data={"key": "value"},
+        )
+
+    tool_prompt_node = create_tool_prompt_node(
+        ml_model="test-model",
+        blocks=[],
+        functions=[failing_function],
+        prompt_inputs=None,
+        parameters=DEFAULT_PROMPT_PARAMETERS,
+    )
+
+    function_node_class = create_function_node(
+        function=failing_function,
+        tool_prompt_node=tool_prompt_node,
+    )
+
+    state = ToolCallingState(
+        meta=StateMeta(
+            node_outputs={
+                tool_prompt_node.Outputs.results: [
+                    FunctionCallVellumValue(
+                        value=FunctionCall(
+                            arguments={},
+                            id="call_123",
+                            name="failing_function",
+                            state="FULFILLED",
+                        ),
+                    )
+                ],
+            },
+        )
+    )
+
+    function_node = function_node_class(state=state)
+
+    with pytest.raises(NodeException) as exc_info:
+        list(function_node.run())
+
+    e = exc_info.value
+    assert e.code == WorkflowErrorCode.INVALID_INPUTS
+    assert e.raw_data == {"key": "value"}
+    assert "Custom error" in e.message

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

@@ -55,6 +55,28 @@ class FunctionCallNodeMixin:
 
     function_call_output: List[PromptOutput]
 
+    def _handle_tool_exception(self, e: Exception, tool_type: str, tool_name: str) -> None:
+        """
+        Re-raise exceptions with contextual information while preserving NodeException details.
+
+        Args:
+            e: The caught exception
+            tool_type: Type of tool (e.g., "function", "MCP tool", "Vellum Integration tool")
+            tool_name: Name of the tool that failed
+        """
+        if isinstance(e, NodeException):
+            # Preserve original error code and raw_data while adding context
+            raise NodeException(
+                message=f"Error executing {tool_type} '{tool_name}': {e.message}",
+                code=e.code,
+                raw_data=e.raw_data,
+            ) from e
+        else:
+            raise NodeException(
+                message=f"Error executing {tool_type} '{tool_name}': {str(e)}",
+                code=WorkflowErrorCode.NODE_EXECUTION,
+            ) from e
+
     def _extract_function_arguments(self) -> dict:
         """Extract arguments from function call output."""
         current_index = getattr(self, "state").current_prompt_output_index
@@ -201,11 +223,7 @@ class FunctionNode(BaseNode[ToolCallingState], FunctionCallNodeMixin):
         try:
             result = self.function_definition(**arguments)
         except Exception as e:
-            function_name = self.function_definition.__name__
-            raise NodeException(
-                message=f"Error executing function '{function_name}': {str(e)}",
-                code=WorkflowErrorCode.NODE_EXECUTION,
-            ) from e
+            self._handle_tool_exception(e, "function", self.function_definition.__name__)
 
         # Add the result to the chat history
         self._add_function_result_to_chat_history(result, self.state)
@@ -232,10 +250,7 @@ class ComposioNode(BaseNode[ToolCallingState], FunctionCallNodeMixin):
             else:
                 result = composio_service.execute_tool(tool_name=self.composio_tool.action, arguments=arguments)
         except Exception as e:
-            raise NodeException(
-                message=f"Error executing Composio tool '{self.composio_tool.action}': {str(e)}",
-                code=WorkflowErrorCode.NODE_EXECUTION,
-            ) from e
+            self._handle_tool_exception(e, "Composio tool", self.composio_tool.action)
 
         # Add result to chat history
         self._add_function_result_to_chat_history(result, self.state)
@@ -255,10 +270,7 @@ class MCPNode(BaseNode[ToolCallingState], FunctionCallNodeMixin):
             mcp_service = MCPService()
             result = mcp_service.execute_tool(tool_def=self.mcp_tool, arguments=arguments)
         except Exception as e:
-            raise NodeException(
-                message=f"Error executing MCP tool '{self.mcp_tool.name}': {str(e)}",
-                code=WorkflowErrorCode.NODE_EXECUTION,
-            ) from e
+            self._handle_tool_exception(e, "MCP tool", self.mcp_tool.name)
 
         # Add result to chat history
         self._add_function_result_to_chat_history(result, self.state)
@@ -283,18 +295,8 @@ class VellumIntegrationNode(BaseNode[ToolCallingState], FunctionCallNodeMixin):
                 tool_name=self.vellum_integration_tool.name,
                 arguments=arguments,
             )
-        except NodeException as e:
-            # Preserve original error code and raw_data while adding context
-            raise NodeException(
-                message=f"Error executing Vellum Integration tool '{self.vellum_integration_tool.name}': {e.message}",
-                code=e.code,
-                raw_data=e.raw_data,
-            ) from e
         except Exception as e:
-            raise NodeException(
-                message=f"Error executing Vellum Integration tool '{self.vellum_integration_tool.name}': {str(e)}",
-                code=WorkflowErrorCode.NODE_EXECUTION,
-            ) from e
+            self._handle_tool_exception(e, "Vellum Integration tool", self.vellum_integration_tool.name)
 
         # Add result to chat history
         self._add_function_result_to_chat_history(result, self.state)

vellum/workflows/runner/runner.py

@@ -466,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:
@@ -529,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()
@@ -736,22 +724,24 @@ class WorkflowRunner(Generic[StateType]):
             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,
-                span_id=span_id,
-                body=NodeExecutionRejectedBody(
-                    node_definition=active_node.node.__class__,
-                    error=WorkflowError(
-                        code=WorkflowErrorCode.NODE_CANCELLED,
-                        message=error_message,
+        active_span_ids = list(self._active_nodes_by_execution_id.keys())
+        for span_id in active_span_ids:
+            active_node = self._active_nodes_by_execution_id.pop(span_id, None)
+            if active_node is not None:
+                rejection_event = NodeExecutionRejectedEvent(
+                    trace_id=self._execution_context.trace_id,
+                    span_id=span_id,
+                    body=NodeExecutionRejectedBody(
+                        node_definition=active_node.node.__class__,
+                        error=WorkflowError(
+                            code=WorkflowErrorCode.NODE_CANCELLED,
+                            message=error_message,
+                        ),
+                        stacktrace=captured_stacktrace,
                     ),
-                    stacktrace=captured_stacktrace,
-                ),
-                parent=parent_context,
-            )
-            self._workflow_event_outer_queue.put(rejection_event)
-            self._active_nodes_by_execution_id.pop(span_id)
+                    parent=parent_context,
+                )
+                self._workflow_event_outer_queue.put(rejection_event)
 
     def _initiate_workflow_event(self) -> WorkflowExecutionInitiatedEvent:
         links: Optional[List[SpanLink]] = None

vellum/workflows/triggers/__init__.py

@@ -1,4 +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", "ManualTrigger"]
+__all__ = ["BaseTrigger", "IntegrationTrigger", "ManualTrigger"]

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/tests/__init__.py

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