vellum-ai 1.7.9__py3-none-any.whl → 1.7.11__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.9",
+            "User-Agent": "vellum-ai/1.7.11",
             "X-Fern-Language": "Python",
             "X-Fern-SDK-Name": "vellum-ai",
-            "X-Fern-SDK-Version": "1.7.9",
+            "X-Fern-SDK-Version": "1.7.11",
             **(self.get_custom_headers() or {}),
         }
         if self._api_version is not None:

vellum/workflows/events/tests/test_event.py

@@ -93,6 +93,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     "display_context": None,
                     "initial_state": None,
                     "workflow_version_exec_config": None,
+                    "server_metadata": None,
                 },
                 "parent": None,
                 "links": None,

vellum/workflows/events/workflow.py

@@ -83,6 +83,9 @@ class WorkflowExecutionInitiatedBody(_BaseWorkflowExecutionBody, Generic[InputsT
     # This field will be populated during serialization by the serialize_body method
     workflow_version_exec_config: Optional[Any] = None
 
+    # This field can be populated with arbitrary server metadata during event enrichment
+    server_metadata: Optional[Dict[str, Any]] = None
+
     @field_serializer("inputs")
     def serialize_inputs(self, inputs: InputsType, _info: Any) -> Dict[str, Any]:
         return default_serializer(inputs)

vellum/workflows/exceptions.py

@@ -58,10 +58,12 @@ class WorkflowInitializationException(Exception):
         message: str,
         workflow_definition: Optional[Type["BaseWorkflow"]] = None,
         code: WorkflowErrorCode = WorkflowErrorCode.INVALID_INPUTS,
+        raw_data: Optional[Dict[str, Any]] = None,
     ):
 
         self.message = message
         self.code = code
+        self.raw_data = raw_data
         self.definition = workflow_definition if workflow_definition is not None else import_workflow_class()
         super().__init__(message)
 
@@ -70,4 +72,5 @@ class WorkflowInitializationException(Exception):
         return WorkflowError(
             message=self.message,
             code=self.code,
+            raw_data=self.raw_data,
         )

vellum/workflows/integrations/mcp_service.py

@@ -1,6 +1,7 @@
 import asyncio
 import json
 import logging
+import traceback
 from typing import Any, Dict, List, Optional
 
 import httpx
@@ -226,6 +227,8 @@ class MCPService:
             raise NodeException(
                 message=f"Error executing MCP operation '{operation}': {str(e)}",
                 code=WorkflowErrorCode.NODE_EXECUTION,
+                stacktrace=traceback.format_exc(),
+                raw_data={"operation": operation, "error_type": type(e).__name__, "error_message": str(e)},
             )
 
     def list_tools(self, server: MCPServer) -> List[Dict[str, Any]]:
@@ -249,11 +252,15 @@ class MCPService:
                 )
             )
             return result
+        except NodeException:
+            raise
         except Exception as e:
             logger.error(f"Error executing MCP tool '{tool_def.name}': {e}")
             raise NodeException(
                 message=f"Error executing MCP tool '{tool_def.name}': {str(e)}",
                 code=WorkflowErrorCode.NODE_EXECUTION,
+                stacktrace=traceback.format_exc(),
+                raw_data={"tool_name": tool_def.name, "error_type": type(e).__name__, "error_message": str(e)},
             )
 
     def hydrate_tool_definitions(self, server_def: MCPServer) -> List[MCPToolDefinition]:

vellum/workflows/integrations/tests/test_mcp_service.py

@@ -4,6 +4,8 @@ import json
 from unittest import mock
 
 from vellum.workflows.constants import AuthorizationType
+from vellum.workflows.errors.types import WorkflowErrorCode
+from vellum.workflows.exceptions import NodeException
 from vellum.workflows.integrations.mcp_service import MCPHttpClient, MCPService
 from vellum.workflows.types.definition import MCPServer, MCPToolDefinition
 
@@ -223,3 +225,49 @@ def test_mcp_service_list_tools_handles_errors():
 
         # THEN we should get an empty list instead of crashing
         assert tools == []
+
+
+def test_mcp_service_call_tool_includes_stacktrace_and_raw_data_on_error():
+    """
+    Tests that NodeException contains stacktrace and raw_data when call_tool errors.
+    """
+    # GIVEN an MCP server configuration
+    sample_mcp_server = MCPServer(
+        name="test-server",
+        url="https://test.mcp.server.com/mcp",
+        authorization_type=AuthorizationType.BEARER_TOKEN,
+        bearer_token_value="test-token",
+    )
+
+    tool_def = MCPToolDefinition(
+        name="test-tool",
+        server=sample_mcp_server,
+        description="A test tool",
+        parameters={},
+    )
+
+    # AND a mock httpx client that raises an exception during tool execution
+    with mock.patch("vellum.workflows.integrations.mcp_service.httpx.AsyncClient") as mock_client_class:
+        mock_client = mock.AsyncMock()
+        mock_client_class.return_value = mock_client
+        mock_client.post.side_effect = RuntimeError("Tool execution failed")
+
+        # WHEN we try to execute the tool
+        service = MCPService()
+
+        with pytest.raises(NodeException) as exc_info:
+            service.execute_tool(tool_def, {"arg": "value"})
+
+        # THEN the exception should have the correct error code
+        assert exc_info.value.code == WorkflowErrorCode.NODE_EXECUTION
+
+        # AND the exception should have a stacktrace
+        assert exc_info.value.stacktrace is not None
+        assert len(exc_info.value.stacktrace) > 0
+        assert "RuntimeError: Tool execution failed" in exc_info.value.stacktrace
+
+        # AND the exception should have raw_data with operation details
+        assert exc_info.value.raw_data is not None
+        assert exc_info.value.raw_data["operation"] == "call_tool"
+        assert exc_info.value.raw_data["error_type"] == "RuntimeError"
+        assert exc_info.value.raw_data["error_message"] == "Tool execution failed"

vellum/workflows/loaders/__init__.py

@@ -0,0 +1,3 @@
+from vellum.workflows.loaders.base import BaseWorkflowFinder
+
+__all__ = ["BaseWorkflowFinder"]

vellum/workflows/loaders/base.py

@@ -0,0 +1,21 @@
+from abc import ABC, abstractmethod
+import importlib.abc
+
+
+class BaseWorkflowFinder(importlib.abc.MetaPathFinder, ABC):
+    """
+    Abstract base class for workflow finders that support custom error message formatting.
+    """
+
+    @abstractmethod
+    def format_error_message(self, error_message: str) -> str:
+        """
+        Format an error message to be more user-friendly.
+
+        Args:
+            error_message: The original error message
+
+        Returns:
+            The formatted error message
+        """
+        pass

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

@@ -4,9 +4,11 @@ from typing import ClassVar, Generator, Generic, Iterator, List, Optional, Union
 from vellum import AdHocExecutePromptEvent, ExecutePromptEvent, PromptOutput
 from vellum.client.core import RequestOptions
 from vellum.client.core.api_error import ApiError
+from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.errors.types import WorkflowErrorCode, vellum_error_to_workflow_error
 from vellum.workflows.events.node import NodeExecutionStreamingEvent
 from vellum.workflows.exceptions import NodeException
+from vellum.workflows.expressions.coalesce_expression import CoalesceExpression
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.outputs.base import BaseOutput, BaseOutputs
 from vellum.workflows.references.output import OutputReference
@@ -14,6 +16,16 @@ from vellum.workflows.types.core import EntityInputsInterface, MergeBehavior
 from vellum.workflows.types.generics import StateType
 
 
+def _contains_reference_to_output(reference: BaseDescriptor, target_reference: OutputReference) -> bool:
+    if reference == target_reference:
+        return True
+    if isinstance(reference, CoalesceExpression):
+        return _contains_reference_to_output(reference.lhs, target_reference) or _contains_reference_to_output(
+            reference.rhs, target_reference
+        )
+    return False
+
+
 class BasePromptNode(BaseNode[StateType], Generic[StateType]):
     # Inputs that are passed to the Prompt
     prompt_inputs: ClassVar[Optional[EntityInputsInterface]] = None
@@ -112,10 +124,7 @@ class BasePromptNode(BaseNode[StateType], Generic[StateType]):
         if not target_node_output:
             return False
 
-        if not isinstance(target_node_output.instance, OutputReference):
+        if not isinstance(target_node_output.instance, BaseDescriptor):
             return False
 
-        if target_node_output.instance.name != "text":
-            return False
-
-        return True
+        return _contains_reference_to_output(target_node_output.instance, event.node_definition.Outputs.text)

vellum/workflows/tests/triggers/test_vellum_integration_trigger.py

@@ -0,0 +1,225 @@
+"""Tests for VellumIntegrationTrigger factory pattern and behavior."""
+
+import pytest
+
+from vellum.workflows.constants import VellumIntegrationProviderType
+from vellum.workflows.references.trigger import TriggerAttributeReference
+from vellum.workflows.triggers.vellum_integration import VellumIntegrationTrigger
+
+
+def test_factory_creates_trigger_class() -> None:
+    """Factory method creates a trigger class with correct attributes."""
+    SlackNewMessage = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+        attributes={"channel": "C123456"},
+    )
+
+    assert issubclass(SlackNewMessage, VellumIntegrationTrigger)
+    assert SlackNewMessage.provider == VellumIntegrationProviderType.COMPOSIO
+    assert SlackNewMessage.integration_name == "SLACK"
+    assert SlackNewMessage.slug == "slack_new_message"
+    assert SlackNewMessage.trigger_nano_id == "test_nano_123"
+    assert SlackNewMessage.attributes == {"channel": "C123456"}
+
+
+def test_factory_caches_trigger_classes() -> None:
+    """Factory returns the same class instance for identical parameters (ensures deterministic UUIDs)."""
+    SlackNewMessage1 = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+    )
+    SlackNewMessage2 = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+    )
+
+    assert SlackNewMessage1 is SlackNewMessage2
+
+
+def test_populates_dynamic_attributes() -> None:
+    """Trigger dynamically populates attributes from event_data keys."""
+    GithubPush = VellumIntegrationTrigger.for_trigger(
+        integration_name="GITHUB",
+        slug="github_push_event",
+        trigger_nano_id="test_nano_456",
+    )
+
+    event_data = {
+        "repository": "vellum-ai/workflows",
+        "branch": "main",
+        "commits": ["abc123", "def456"],
+    }
+
+    trigger = GithubPush(event_data=event_data)
+
+    assert getattr(trigger, "repository") == "vellum-ai/workflows"
+    assert getattr(trigger, "branch") == "main"
+    assert getattr(trigger, "commits") == ["abc123", "def456"]
+
+
+def test_supports_attribute_references() -> None:
+    """Metaclass creates TriggerAttributeReference dynamically on attribute access."""
+    SlackNewMessage = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+    )
+
+    # Metaclass __getattribute__ creates references for undefined attributes
+    message_ref = SlackNewMessage.message
+    channel_ref = SlackNewMessage.channel
+
+    assert isinstance(message_ref, TriggerAttributeReference)
+    assert isinstance(channel_ref, TriggerAttributeReference)
+    assert message_ref.name == "message"
+    assert channel_ref.name == "channel"
+
+
+def test_to_trigger_attribute_values() -> None:
+    """to_trigger_attribute_values returns correct attribute mappings."""
+    SlackNewMessage = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+    )
+
+    event_data = {"message": "Hello", "channel": "C123"}
+    trigger = SlackNewMessage(event_data=event_data)
+
+    attr_values = trigger.to_trigger_attribute_values()
+
+    assert len(attr_values) == 2
+    for key in attr_values.keys():
+        assert isinstance(key, TriggerAttributeReference)
+    assert set(attr_values.values()) == {"Hello", "C123"}
+
+
+def test_trigger_attribute_id_stability() -> None:
+    """Trigger attribute IDs must be stable across factory calls."""
+    Slack1 = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+    )
+    Slack2 = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+    )
+
+    # Factory caching ensures same class
+    assert Slack1 is Slack2
+
+    # Attribute references must be deterministic across accesses
+    msg_ref_1 = Slack1.message
+    msg_ref_2 = Slack2.message
+
+    # Same trigger class + same attribute name = same reference
+    assert msg_ref_1 == msg_ref_2
+
+
+def test_to_exec_config() -> None:
+    """to_exec_config() produces valid ComposioIntegrationTriggerExecConfig."""
+    SlackMessage = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="abc123def456",
+        attributes={"channel": "C123456"},
+    )
+
+    exec_config = SlackMessage.to_exec_config()
+
+    assert exec_config.type == "COMPOSIO_INTEGRATION_TRIGGER"
+    assert exec_config.provider == VellumIntegrationProviderType.COMPOSIO
+    assert exec_config.integration_name == "SLACK"
+    assert exec_config.slug == "slack_new_message"
+    assert exec_config.trigger_nano_id == "abc123def456"
+    assert exec_config.attributes == {"channel": "C123456"}
+
+
+def test_to_exec_config_base_class_fails() -> None:
+    """to_exec_config() raises error on base class."""
+    with pytest.raises(AttributeError, match="factory-generated trigger classes"):
+        VellumIntegrationTrigger.to_exec_config()
+
+
+def test_empty_event_data() -> None:
+    """Trigger handles empty event data gracefully."""
+    SlackMessage = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+    )
+    trigger = SlackMessage(event_data={})
+
+    attr_values = trigger.to_trigger_attribute_values()
+    assert attr_values == {}
+
+
+def test_attribute_name_does_not_conflict_with_class_variables() -> None:
+    """Event data attributes don't conflict with class variables."""
+    SlackMessage = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+    )
+
+    # Event data with key that matches a class variable name
+    event_data = {"provider": "some_value", "message": "Hello"}
+    trigger = SlackMessage(event_data=event_data)
+
+    # Instance attribute should be set from event_data
+    assert trigger.provider == "some_value"  # Instance attr from event_data
+    # But class variable should be unchanged
+    assert SlackMessage.provider == VellumIntegrationProviderType.COMPOSIO
+
+
+def test_non_json_serializable_attributes_fail_fast() -> None:
+    """Non-JSON-serializable attributes raise ValueError with clear message."""
+
+    # Custom objects are not JSON-serializable
+    class CustomObject:
+        pass
+
+    with pytest.raises(ValueError, match="must be JSON-serializable"):
+        VellumIntegrationTrigger.for_trigger(
+            integration_name="SLACK",
+            slug="slack_new_message",
+            trigger_nano_id="test_nano_123",
+            attributes={"custom": CustomObject()},
+        )
+
+    # Sets are not JSON-serializable
+    with pytest.raises(ValueError, match="must be JSON-serializable"):
+        VellumIntegrationTrigger.for_trigger(
+            integration_name="SLACK",
+            slug="slack_new_message",
+            trigger_nano_id="test_nano_123",
+            attributes={"tags": {"a", "b", "c"}},
+        )
+
+
+def test_nested_json_serializable_attributes_work() -> None:
+    """Nested JSON-serializable attributes work correctly."""
+    SlackMessage = VellumIntegrationTrigger.for_trigger(
+        integration_name="SLACK",
+        slug="slack_new_message",
+        trigger_nano_id="test_nano_123",
+        attributes={
+            "channel": "C123456",
+            "filters": {"status": "active", "priority": ["high", "medium"]},
+            "count": 42,
+            "enabled": True,
+        },
+    )
+
+    assert SlackMessage.attributes == {
+        "channel": "C123456",
+        "filters": {"status": "active", "priority": ["high", "medium"]},
+        "count": 42,
+        "enabled": True,
+    }

vellum/workflows/triggers/__init__.py

@@ -2,5 +2,6 @@ from vellum.workflows.triggers.base import BaseTrigger
 from vellum.workflows.triggers.integration import IntegrationTrigger
 from vellum.workflows.triggers.manual import ManualTrigger
 from vellum.workflows.triggers.slack import SlackTrigger
+from vellum.workflows.triggers.vellum_integration import VellumIntegrationTrigger
 
-__all__ = ["BaseTrigger", "IntegrationTrigger", "ManualTrigger", "SlackTrigger"]
+__all__ = ["BaseTrigger", "IntegrationTrigger", "ManualTrigger", "SlackTrigger", "VellumIntegrationTrigger"]