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

vellum/workflows/triggers/integration.py

@@ -0,0 +1,198 @@
+from abc import ABC
+from typing import Any, ClassVar, Dict
+
+from vellum.workflows.constants import VellumIntegrationProviderType
+from vellum.workflows.references.trigger import TriggerAttributeReference
+from vellum.workflows.triggers.base import BaseTrigger, BaseTriggerMeta
+
+
+class IntegrationTriggerMeta(BaseTriggerMeta):
+    """
+    Custom metaclass for IntegrationTrigger.
+
+    This metaclass extends BaseTriggerMeta to automatically convert type annotations
+    into TriggerAttributeReference objects during class creation. This enables trigger
+    attributes to be referenced in workflow graphs while maintaining type safety.
+
+    It also sets __trigger_name__ based on Config.slug for trigger name resolution.
+    """
+
+    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any) -> "IntegrationTriggerMeta":
+        """Create a new trigger class and set up attribute references."""
+        cls = super().__new__(mcs, name, bases, namespace, **kwargs)
+
+        # Process __annotations__ to create TriggerAttributeReference for each attribute
+        # Only process if class has Config and annotations
+        has_config = hasattr(cls, "Config") and "Config" in namespace
+        if has_config and hasattr(cls, "__annotations__"):
+            # Create TriggerAttributeReference for each annotated attribute
+            for attr_name, attr_type in cls.__annotations__.items():
+                # Skip special attributes and Config
+                if attr_name.startswith("_") or attr_name == "Config":
+                    continue
+
+                # Create reference with proper type
+                reference = TriggerAttributeReference(
+                    name=attr_name, types=(attr_type,), instance=None, trigger_class=cls
+                )
+                # Set as class attribute so it's directly accessible
+                setattr(cls, attr_name, reference)
+
+        # Set __trigger_name__ based on Config.slug if available
+        if has_config:
+            config_class = namespace.get("Config")
+            if config_class is not None:
+                slug = getattr(config_class, "slug", None)
+                if slug:
+                    cls.__trigger_name__ = str(slug)
+                else:
+                    cls.__trigger_name__ = "integration"
+
+        return cls
+
+
+class IntegrationTrigger(BaseTrigger, ABC, metaclass=IntegrationTriggerMeta):
+    """
+    Base class for Vellum-managed integration triggers.
+
+    Subclasses define two types of attributes:
+    1. **Config class**: Specifies how the trigger is configured (provider, integration_name, slug)
+       - These are configuration details users shouldn't need to interact with directly
+    2. **Top-level type annotations**: Define the webhook event payload structure (message, user, channel, etc.)
+       - These become TriggerAttributeReference that can be referenced in workflow nodes
+
+    Examples:
+        Create a Slack trigger:
+            >>> class SlackNewMessageTrigger(IntegrationTrigger):
+            ...     # Event attributes (webhook payload structure)
+            ...     message: str
+            ...     user: str
+            ...     channel: str
+            ...     timestamp: float
+            ...
+            ...     # Configuration (how trigger is set up)
+            ...     class Config(IntegrationTrigger.Config):
+            ...         provider = VellumIntegrationProviderType.COMPOSIO
+            ...         integration_name = "SLACK"
+            ...         slug = "slack_new_message"
+
+        Use in workflow graph:
+            >>> class MyWorkflow(BaseWorkflow):
+            ...     graph = SlackNewMessageTrigger >> ProcessMessageNode
+
+        Reference trigger attributes in nodes:
+            >>> class ProcessNode(BaseNode):
+            ...     class Outputs(BaseNode.Outputs):
+            ...         text = SlackNewMessageTrigger.message
+            ...         channel = SlackNewMessageTrigger.channel
+
+        Instantiate for testing:
+            >>> trigger = SlackNewMessageTrigger(
+            ...     message="Hello world",
+            ...     channel="C123456",
+            ...     user="U123",
+            ...     timestamp=1234567890.0,
+            ... )
+            >>> trigger.message
+            'Hello world'
+    """
+
+    class Config:
+        """
+        Configuration for IntegrationTrigger subclasses.
+
+        Defines how the trigger connects to the integration provider. These settings
+        specify which integration and which specific trigger type to use.
+        """
+
+        provider: ClassVar[VellumIntegrationProviderType]
+        integration_name: ClassVar[str]
+        slug: ClassVar[str]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Validate that subclasses define required Config class with all required fields."""
+        super().__init_subclass__(**kwargs)
+
+        # Skip validation for the base class itself
+        if cls.__name__ == "IntegrationTrigger":
+            return
+
+        # Require Config class with required fields
+        if not hasattr(cls, "Config") or cls.Config is IntegrationTrigger.Config:
+            raise TypeError(
+                f"{cls.__name__} must define a nested Config class. "
+                f"Example:\n"
+                f"  class {cls.__name__}(IntegrationTrigger):\n"
+                f"      message: str\n"
+                f"      class Config(IntegrationTrigger.Config):\n"
+                f"          provider = VellumIntegrationProviderType.COMPOSIO\n"
+                f"          integration_name = 'SLACK'\n"
+                f"          slug = 'slack_new_message'"
+            )
+
+        # Validate Config class has required fields
+        config_cls = cls.Config
+        required_fields = ["provider", "integration_name", "slug"]
+        for field in required_fields:
+            if not hasattr(config_cls, field):
+                raise TypeError(
+                    f"{cls.__name__}.Config must define '{field}'. " f"Required fields: {', '.join(required_fields)}"
+                )
+
+    def __init__(self, **kwargs: Any):
+        """
+        Initialize trigger with event data from the integration.
+
+        The trigger dynamically populates its attributes based on the kwargs
+        dictionary keys. Any key in kwargs becomes an accessible attribute.
+
+        Examples:
+            >>> class SlackTrigger(IntegrationTrigger):
+            ...     message: str
+            ...     channel: str
+            ...     user: str
+            ...
+            ...     class Config(IntegrationTrigger.Config):
+            ...         provider = VellumIntegrationProviderType.COMPOSIO
+            ...         integration_name = "SLACK"
+            ...         slug = "slack_new_message"
+            >>> trigger = SlackTrigger(
+            ...     message="Hello",
+            ...     channel="C123",
+            ...     user="U456"
+            ... )
+            >>> trigger.message
+            'Hello'
+            >>> trigger.channel
+            'C123'
+        """
+        super().__init__(**kwargs)
+
+        # Dynamically populate instance attributes from kwargs.
+        # This allows any key in kwargs to become an accessible attribute:
+        # kwargs={"message": "Hi"} → trigger.message == "Hi"
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    def to_trigger_attribute_values(self) -> Dict["TriggerAttributeReference[Any]", Any]:
+        """
+        Materialize attribute descriptor/value pairs for this trigger instance.
+
+        For IntegrationTrigger, this includes all dynamic attributes from event_data.
+        """
+        attribute_values: Dict["TriggerAttributeReference[Any]", Any] = {}
+
+        # Unlike the base class which iterates over type(self) (predefined annotations),
+        # we iterate over event_data keys since our attributes are discovered dynamically
+        # from the actual event data received during workflow execution.
+        # The base class approach: for reference in type(self)
+        # Our approach: for attr_name in self._event_data.keys()
+        for attr_name in self._event_data.keys():
+            # Get the class-level reference for this attribute (created by __new__ from annotations)
+            # Unknown keys can appear in webhook payloads, so gracefully skip them if the
+            # trigger class doesn't expose a corresponding reference.
+            reference = getattr(type(self), attr_name, None)
+            if isinstance(reference, TriggerAttributeReference):
+                attribute_values[reference] = getattr(self, attr_name)
+
+        return attribute_values

vellum/workflows/triggers/manual.py

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

vellum/workflows/triggers/schedule.py

@@ -0,0 +1,20 @@
+from datetime import datetime
+from typing import ClassVar, Optional
+
+from vellum.workflows.triggers.base import BaseTrigger
+
+
+class ScheduleTrigger(BaseTrigger):
+    """
+    Trigger representing time-based workflow invocation.
+    Supports Cron-based schedules (e.g., "0 9 * * MON" for every Monday at 9am)
+    """
+
+    current_run_at: datetime
+    next_run_at: datetime
+
+    class Config:
+        cron: str
+        timezone: Optional[str] = None
+
+    __trigger_name__: ClassVar[str] = "scheduled"

vellum/workflows/triggers/tests/__init__.py

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

vellum/workflows/triggers/tests/test_base_trigger_display.py

@@ -0,0 +1,147 @@
+"""Tests for BaseTrigger.Display nested class."""
+
+from vellum.workflows.constants import VellumIntegrationProviderType
+from vellum.workflows.triggers.base import BaseTrigger
+from vellum.workflows.triggers.integration import IntegrationTrigger
+
+
+def test_base_trigger__has_display_class():
+    """
+    Tests that BaseTrigger has a Display nested class with default attributes.
+    """
+
+    display_class = BaseTrigger.Display
+
+    assert display_class is not None
+    assert hasattr(display_class, "label")
+    assert hasattr(display_class, "x")
+    assert hasattr(display_class, "y")
+    assert hasattr(display_class, "z_index")
+    assert hasattr(display_class, "icon")
+    assert hasattr(display_class, "color")
+
+    assert display_class.label == "Trigger"
+    assert display_class.x == 0.0
+    assert display_class.y == 0.0
+    assert display_class.z_index == 0.0
+    assert display_class.icon is None
+    assert display_class.color is None
+
+
+def test_base_trigger__display_class_inheritance():
+    """
+    Tests that trigger subclasses automatically inherit Display class.
+    """
+
+    class CustomTrigger(IntegrationTrigger):
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+    display_class = CustomTrigger.Display
+
+    assert display_class is not None
+    assert issubclass(display_class, BaseTrigger.Display)
+
+    assert hasattr(display_class, "label")
+    assert hasattr(display_class, "x")
+    assert hasattr(display_class, "y")
+    assert hasattr(display_class, "z_index")
+    assert hasattr(display_class, "icon")
+    assert hasattr(display_class, "color")
+
+
+def test_base_trigger__display_class_can_be_overridden():
+    """
+    Tests that trigger subclasses can override Display class attributes.
+    """
+
+    class CustomTrigger(IntegrationTrigger):
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+        class Display(IntegrationTrigger.Display):
+            label = "Custom Trigger"
+            icon = "🎨"
+            color = "#FF5733"
+
+    display_class = CustomTrigger.Display
+
+    assert display_class.label == "Custom Trigger"
+    assert display_class.icon == "🎨"
+    assert display_class.color == "#FF5733"
+
+    assert display_class.x == 0.0
+    assert display_class.y == 0.0
+    assert display_class.z_index == 0.0
+
+
+def test_base_trigger__display_class_multi_level_inheritance():
+    """
+    Tests that Display class inheritance works across multiple levels.
+    """
+
+    class MiddleTrigger(IntegrationTrigger):
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+        class Display(IntegrationTrigger.Display):
+            label = "Middle Trigger"
+            icon = "🔧"
+
+    class LeafTrigger(MiddleTrigger):
+        class Config(MiddleTrigger.Config):
+            slug = "leaf_test"
+
+    display_class = LeafTrigger.Display
+
+    assert issubclass(display_class, MiddleTrigger.Display)
+    assert issubclass(display_class, BaseTrigger.Display)
+
+    assert display_class.label == "Middle Trigger"
+    assert display_class.icon == "🔧"
+
+    assert display_class.x == 0.0
+    assert display_class.y == 0.0
+    assert display_class.z_index == 0.0
+    assert display_class.color is None
+
+
+def test_base_trigger__display_class_override_in_leaf():
+    """
+    Tests that leaf triggers can override Display attributes from parent.
+    """
+
+    class MiddleTrigger(IntegrationTrigger):
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+        class Display(IntegrationTrigger.Display):
+            label = "Middle Trigger"
+            icon = "🔧"
+
+    class LeafTrigger(MiddleTrigger):
+        class Config(MiddleTrigger.Config):
+            slug = "leaf_test"
+
+        class Display(MiddleTrigger.Display):
+            label = "Leaf Trigger"
+            color = "#00FF00"
+
+    display_class = LeafTrigger.Display
+
+    assert display_class.label == "Leaf Trigger"
+    assert display_class.color == "#00FF00"
+
+    assert display_class.icon == "🔧"
+
+    assert display_class.x == 0.0
+    assert display_class.y == 0.0
+    assert display_class.z_index == 0.0

vellum/workflows/triggers/tests/test_chat_message.py

@@ -0,0 +1,257 @@
+"""Tests for ChatMessageTrigger."""
+
+import pytest
+from typing import List, Optional
+
+from pydantic import Field
+
+from vellum.client.types import (
+    ArrayChatMessageContent,
+    ArrayChatMessageContentItem,
+    ChatMessage,
+    ImageChatMessageContent,
+    StringChatMessageContent,
+    StringVellumValue,
+    VellumImage,
+)
+from vellum.workflows.inputs.base import BaseInputs
+from vellum.workflows.nodes.bases.base import BaseNode
+from vellum.workflows.outputs import BaseOutputs
+from vellum.workflows.state.base import BaseState
+from vellum.workflows.triggers.chat_message import ChatMessageTrigger
+from vellum.workflows.workflows.base import BaseWorkflow
+
+
+class ChatState(BaseState):
+    chat_history: List[ChatMessage] = Field(default_factory=list)
+
+
+@pytest.mark.parametrize(
+    ["message", "expected_content"],
+    [
+        pytest.param(
+            [StringChatMessageContent(value="Hello, world!")],
+            ArrayChatMessageContent(value=[StringChatMessageContent(value="Hello, world!")]),
+            id="text_string_content",
+        ),
+        pytest.param(
+            [ImageChatMessageContent(value=VellumImage(src="https://example.com/image.jpg"))],
+            ArrayChatMessageContent(
+                value=[ImageChatMessageContent(value=VellumImage(src="https://example.com/image.jpg"))]
+            ),
+            id="multimodal_image",
+        ),
+        pytest.param(
+            [
+                StringChatMessageContent(value="Look at this image:"),
+                ImageChatMessageContent(value=VellumImage(src="https://example.com/image.jpg")),
+            ],
+            ArrayChatMessageContent(
+                value=[
+                    StringChatMessageContent(value="Look at this image:"),
+                    ImageChatMessageContent(value=VellumImage(src="https://example.com/image.jpg")),
+                ]
+            ),
+            id="text_and_multimodal_array",
+        ),
+    ],
+)
+def test_chat_message_trigger__initiated(
+    message: List[ArrayChatMessageContentItem],
+    expected_content: ArrayChatMessageContent,
+):
+    """Tests that ChatMessageTrigger appends user message on workflow initiation."""
+
+    # GIVEN a ChatMessageTrigger with a message
+    trigger = ChatMessageTrigger(message=message)
+
+    # AND a state with chat_history
+    state = ChatState()
+
+    # WHEN the initiated lifecycle hook is called
+    trigger.__on_workflow_initiated__(state)
+
+    # THEN the user message is appended to chat_history
+    assert len(state.chat_history) == 1
+    assert state.chat_history[0].role == "USER"
+    assert state.chat_history[0].text is None
+    assert state.chat_history[0].content == expected_content
+
+
+def test_chat_message_trigger__state_without_chat_history():
+    """Tests that ChatMessageTrigger handles state without chat_history gracefully."""
+
+    # GIVEN a ChatMessageTrigger with a message
+    trigger = ChatMessageTrigger(message=[StringChatMessageContent(value="Hello")])
+
+    # AND a state without chat_history attribute
+    state = BaseState()
+
+    # WHEN the initiated lifecycle hook is called
+    trigger.__on_workflow_initiated__(state)
+
+    # THEN no error is raised and state is unchanged
+    assert not hasattr(state, "chat_history")
+
+
+def test_chat_message_trigger__graph_syntax():
+    """Tests that ChatMessageTrigger can be used in graph syntax."""
+
+    # GIVEN a ChatMessageTrigger and a node
+    class TestNode(BaseNode):
+        pass
+
+    # WHEN we use trigger >> node syntax
+    graph = ChatMessageTrigger >> TestNode
+
+    # THEN a graph is created with the trigger edge
+    assert graph is not None
+    assert len(list(graph.trigger_edges)) == 1
+    assert list(graph.trigger_edges)[0].trigger_class == ChatMessageTrigger
+    assert list(graph.trigger_edges)[0].to_node == TestNode
+
+
+def test_chat_message_trigger__converts_vellum_value_objects():
+    """Tests that ChatMessageTrigger converts VellumValue objects to ChatMessageContent."""
+
+    # GIVEN a message as VellumValue objects (as received from codegen/API)
+    vellum_value_message = [
+        StringVellumValue(type="STRING", value="Hello, world!"),
+    ]
+
+    # WHEN a ChatMessageTrigger is created with VellumValue objects
+    trigger = ChatMessageTrigger(message=vellum_value_message)
+
+    # THEN the message is converted to ChatMessageContent
+    assert len(trigger.message) == 1
+    assert isinstance(trigger.message[0], StringChatMessageContent)
+    assert trigger.message[0].value == "Hello, world!"
+
+    # AND the trigger works correctly with state
+    state = ChatState()
+    trigger.__on_workflow_initiated__(state)
+
+    assert len(state.chat_history) == 1
+    assert state.chat_history[0].role == "USER"
+    assert state.chat_history[0].content == ArrayChatMessageContent(
+        value=[StringChatMessageContent(value="Hello, world!")]
+    )
+
+
+def test_chat_message_trigger__converts_dict_format():
+    """Tests that ChatMessageTrigger converts dict format to ChatMessageContent."""
+
+    # GIVEN a message as dict objects (alternative API format)
+    dict_message = [
+        {"type": "STRING", "value": "Hello from dict!"},
+    ]
+
+    # WHEN a ChatMessageTrigger is created with dict objects
+    trigger = ChatMessageTrigger(message=dict_message)
+
+    # THEN the message is converted to ChatMessageContent
+    assert len(trigger.message) == 1
+    assert isinstance(trigger.message[0], StringChatMessageContent)
+    assert trigger.message[0].value == "Hello from dict!"
+
+
+def test_chat_message_trigger__converts_string_message():
+    """Tests that ChatMessageTrigger converts string messages to ChatMessageContent list."""
+
+    # GIVEN a message as a string
+    string_message = "Hello, world!"
+
+    # WHEN a ChatMessageTrigger is created with a string message
+    trigger = ChatMessageTrigger(message=string_message)
+
+    # THEN the message is converted to a list with a single StringChatMessageContent
+    assert len(trigger.message) == 1
+    assert isinstance(trigger.message[0], StringChatMessageContent)
+    assert trigger.message[0].value == "Hello, world!"
+
+    # AND the trigger works correctly with state
+    state = ChatState()
+    trigger.__on_workflow_initiated__(state)
+
+    assert len(state.chat_history) == 1
+    assert state.chat_history[0].role == "USER"
+    assert state.chat_history[0].content == ArrayChatMessageContent(
+        value=[StringChatMessageContent(value="Hello, world!")]
+    )
+
+
+def test_chat_message_trigger__raw_string_array__workflow_stream():
+    """Tests that workflow.stream() works with raw string array after deserialize_trigger."""
+
+    # GIVEN a workflow with ChatMessageTrigger
+    class TestNode(BaseNode):
+        class Outputs(BaseOutputs):
+            result: str
+
+        def run(self) -> Outputs:
+            return self.Outputs(result="success")
+
+    class TestWorkflow(BaseWorkflow):
+        graph = ChatMessageTrigger >> TestNode
+
+    # AND a raw string array input (not wrapped in VellumValue format)
+    raw_string_array_input = {"message": ["Hello", "World"]}
+
+    # WHEN we deserialize the trigger with raw string array
+    trigger = TestWorkflow.deserialize_trigger(
+        trigger_id=ChatMessageTrigger.__id__,
+        inputs=raw_string_array_input,
+    )
+
+    # THEN the trigger is properly deserialized
+    assert isinstance(trigger, ChatMessageTrigger)
+    assert len(trigger.message) == 2
+    assert isinstance(trigger.message[0], StringChatMessageContent)
+    assert trigger.message[0].value == "Hello"
+    assert isinstance(trigger.message[1], StringChatMessageContent)
+    assert trigger.message[1].value == "World"
+
+    # AND the workflow can be streamed successfully
+    workflow = TestWorkflow()
+    events = list(workflow.stream(trigger=trigger))
+
+    # THEN the workflow completes successfully
+    assert len(events) > 0
+
+
+def test_chat_message_trigger__chat_history_defaulted_to_none():
+    """Tests that workflow runs successfully when chat_history is defaulted to None."""
+
+    # GIVEN a state with chat_history defaulted to None
+    class NullableChatHistoryState(BaseState):
+        chat_history: Optional[List[ChatMessage]] = None
+
+    # AND a simple node
+    class TestNode(BaseNode):
+        class Outputs(BaseOutputs):
+            result: str
+
+        def run(self) -> Outputs:
+            return self.Outputs(result="success")
+
+    # AND a workflow with ChatMessageTrigger and the nullable chat_history state
+    class TestWorkflow(BaseWorkflow[BaseInputs, NullableChatHistoryState]):
+        graph = ChatMessageTrigger >> TestNode
+
+    # WHEN we run the workflow with a trigger
+    trigger = ChatMessageTrigger(message="Hello")
+    workflow = TestWorkflow()
+    terminal_event = workflow.run(trigger=trigger)
+
+    # THEN the workflow completes successfully
+    assert terminal_event.name == "workflow.execution.fulfilled"
+
+    # AND the final state has a contentful chat_history
+    final_state = terminal_event.final_state
+    assert final_state is not None
+    assert final_state.chat_history is not None
+    assert len(final_state.chat_history) == 1
+    assert final_state.chat_history[0].role == "USER"
+    assert final_state.chat_history[0].content == ArrayChatMessageContent(
+        value=[StringChatMessageContent(value="Hello")]
+    )