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

vellum/workflows/triggers/integration.py

@@ -0,0 +1,186 @@
+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.
+    """
+
+    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)
+
+        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,37 @@
+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
+    """
+
+    pass

vellum/workflows/triggers/schedule.py

@@ -0,0 +1,18 @@
+from datetime import datetime
+from typing import 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

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_integration.py

@@ -0,0 +1,155 @@
+"""Tests for IntegrationTrigger base class."""
+
+from typing import Any
+
+from vellum.workflows.constants import VellumIntegrationProviderType
+from vellum.workflows.nodes.bases.base import BaseNode
+from vellum.workflows.references.trigger import TriggerAttributeReference
+from vellum.workflows.state.base import BaseState
+from vellum.workflows.triggers.integration import IntegrationTrigger
+
+
+def test_integration_trigger__can_be_instantiated_as_base():
+    """IntegrationTrigger can be instantiated as a base class."""
+    # WHEN we instantiate IntegrationTrigger directly
+    trigger = IntegrationTrigger(test="data")
+
+    # THEN it creates an instance with event data stored
+    assert trigger._event_data == {"test": "data"}
+
+
+def test_integration_trigger__can_be_instantiated():
+    """IntegrationTrigger can be instantiated for testing."""
+
+    # GIVEN IntegrationTrigger with concrete implementation
+    class TestTrigger(IntegrationTrigger):
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+    # THEN it can be instantiated (even though base is ABC, concrete subclasses work)
+    assert TestTrigger is not None
+
+
+def test_integration_trigger__can_be_subclassed():
+    """IntegrationTrigger can be subclassed to create concrete triggers."""
+
+    # GIVEN a concrete implementation of IntegrationTrigger
+    class TestTrigger(IntegrationTrigger):
+        data: str
+
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+        def __init__(self, **kwargs: Any):
+            super().__init__(**kwargs)
+            self.data = kwargs.get("data", "")
+
+    # WHEN we create a trigger instance
+    result = TestTrigger(data="test")
+
+    # THEN it returns the expected trigger instance with populated attributes
+    assert result.data == "test"
+
+
+def test_integration_trigger__attribute_reference():
+    """Trigger annotations expose TriggerAttributeReference descriptors."""
+
+    class TestTrigger(IntegrationTrigger):
+        value: str
+
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+        def __init__(self, **kwargs: Any):
+            super().__init__(**kwargs)
+            self.value = kwargs.get("value", "")
+
+    reference = TestTrigger.value
+    assert isinstance(reference, TriggerAttributeReference)
+    assert reference.name == "value"
+    assert TestTrigger.value == reference
+    assert reference == TestTrigger.attribute_references()["value"]
+
+    state = BaseState()
+    trigger = TestTrigger(value="data")
+    trigger.bind_to_state(state)
+    assert reference.resolve(state) == "data"
+
+
+def test_integration_trigger__graph_syntax():
+    """IntegrationTrigger can be used in graph syntax."""
+
+    # GIVEN a concrete trigger and a node
+    class TestTrigger(IntegrationTrigger):
+        value: str
+
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+        def __init__(self, **kwargs: Any):
+            super().__init__(**kwargs)
+            self.value = kwargs.get("value", "")
+
+    class TestNode(BaseNode):
+        pass
+
+    # WHEN we use trigger >> node syntax
+    graph = TestTrigger >> TestNode
+
+    # THEN a graph is created
+    assert graph is not None
+    assert len(list(graph.trigger_edges)) == 1
+    assert list(graph.trigger_edges)[0].trigger_class == TestTrigger
+    assert list(graph.trigger_edges)[0].to_node == TestNode
+
+
+def test_integration_trigger__multiple_entrypoints():
+    """IntegrationTrigger works with multiple entry points."""
+
+    # GIVEN a trigger and multiple nodes
+    class TestTrigger(IntegrationTrigger):
+        msg: str
+
+        class Config(IntegrationTrigger.Config):
+            provider = VellumIntegrationProviderType.COMPOSIO
+            integration_name = "test"
+            slug = "test"
+
+        def __init__(self, **kwargs: Any):
+            super().__init__(**kwargs)
+            self.msg = kwargs.get("msg", "")
+
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    # WHEN we use trigger >> {nodes} syntax
+    graph = TestTrigger >> {NodeA, NodeB}
+
+    # THEN both nodes are entrypoints
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 2
+    target_nodes = {edge.to_node for edge in trigger_edges}
+    assert target_nodes == {NodeA, NodeB}
+
+
+def test_integration_trigger__config_attribute():
+    """IntegrationTrigger requires Config class with provider, integration_name, and slug."""
+
+    # GIVEN IntegrationTrigger
+    # THEN it has a Config class with type annotations for required fields
+    assert hasattr(IntegrationTrigger, "Config")
+    assert hasattr(IntegrationTrigger.Config, "__annotations__")
+    assert "provider" in IntegrationTrigger.Config.__annotations__
+    assert "integration_name" in IntegrationTrigger.Config.__annotations__
+    assert "slug" in IntegrationTrigger.Config.__annotations__

vellum/workflows/types/__init__.py

@@ -1,5 +1,6 @@
-from .core import MergeBehavior
+from .core import CancelSignal, MergeBehavior
 
 __all__ = [
+    "CancelSignal",
     "MergeBehavior",
 ]

vellum/workflows/types/code_execution_node_wrappers.py

@@ -0,0 +1,105 @@
+from vellum.client.types.function_call import FunctionCall
+from vellum.workflows.constants import undefined
+
+
+class StringValueWrapper(str):
+    def __getitem__(self, key):
+        if key == "value":
+            return self
+        if key == "type":
+            return "STRING"
+        return super().__getitem__(key)
+
+    def __getattr__(self, attr):
+        if attr == "value":
+            return self
+        if attr == "type":
+            return "STRING"
+        raise AttributeError(f"'str' object has no attribute '{attr}'")
+
+
+class FunctionCallWrapper(FunctionCall):
+    def __init__(self, obj):
+        super().__init__(arguments=obj.arguments, name=obj.name, id=obj.id)
+
+    def __getitem__(self, key):
+        if key == "value":
+            return self
+        if key == "type":
+            return "FUNCTION_CALL"
+        raise KeyError(key)
+
+    def __getattr__(self, attr):
+        if attr == "value":
+            return self
+        if attr == "type":
+            return "FUNCTION_CALL"
+        raise AttributeError(f"'FunctionCall' object has no attribute '{attr}'")
+
+
+class ListWrapper(list):
+    def __getitem__(self, key):
+        item = super().__getitem__(key)
+        if not isinstance(item, DictWrapper) and not isinstance(item, ListWrapper):
+            self.__setitem__(key, clean_for_dict_wrapper(item))
+
+        return super().__getitem__(key)
+
+    def __getattr__(self, attr):
+        if attr == "value":
+            return self
+        raise AttributeError(f"'list' object has no attribute '{attr}'")
+
+    def __iter__(self):
+        for i in range(len(self)):
+            yield self[i]
+
+
+class DictWrapper(dict):
+    """
+    This wraps a dict object to make it behave basically the same as a standard javascript object
+    and enables us to use vellum types here without a shared library since we don't actually
+    typecheck things here.
+    """
+
+    def __getitem__(self, key):
+        return self.__getattr__(key)
+
+    def __getattr__(self, attr):
+        if attr not in self:
+            if attr == "value":
+                # In order to be backwards compatible with legacy Workflows, which wrapped
+                # several values as VellumValue objects, we use the "value" key to return itself
+                return self
+
+            if attr.startswith("__") and attr.endswith("__"):
+                return super().__getattribute__(attr)
+
+            return undefined
+
+        item = super().__getitem__(attr)
+        if not isinstance(item, DictWrapper) and not isinstance(item, ListWrapper):
+            self.__setattr__(attr, clean_for_dict_wrapper(item))
+
+        return super().__getitem__(attr)
+
+    def __setattr__(self, name, value):
+        self[name] = value
+
+
+def clean_for_dict_wrapper(obj):
+    if isinstance(obj, dict):
+        wrapped = DictWrapper(obj)
+        for key in wrapped.keys():
+            wrapped[key] = clean_for_dict_wrapper(wrapped[key])
+
+        return wrapped
+
+    elif isinstance(obj, list):
+        return ListWrapper(map(lambda item: clean_for_dict_wrapper(item), obj))
+    elif isinstance(obj, str):
+        return StringValueWrapper(obj)
+    elif isinstance(obj, FunctionCall):
+        return FunctionCallWrapper(obj)
+
+    return obj

vellum/workflows/types/core.py

@@ -1,4 +1,6 @@
 from enum import Enum
+from multiprocessing.synchronize import Event as MultiprocessingEvent
+from threading import Event as ThreadingEvent
 from typing import (  # type: ignore[attr-defined]
     Any,
     Dict,
@@ -15,6 +17,8 @@ JsonArray = List["Json"]
 JsonObject = Dict[str, "Json"]
 Json = Union[None, bool, int, float, str, JsonArray, JsonObject]
 
+CancelSignal = Union[ThreadingEvent, MultiprocessingEvent]
+
 # Unions and Generics inherit from `_GenericAlias` instead of `type`
 # In future versions of python, we'll see `_UnionGenericAlias`
 UnderGenericAlias = _GenericAlias
@@ -33,6 +37,7 @@ class MergeBehavior(Enum):
     AWAIT_ALL = "AWAIT_ALL"
     AWAIT_ANY = "AWAIT_ANY"
     AWAIT_ATTRIBUTES = "AWAIT_ATTRIBUTES"
+    CUSTOM = "CUSTOM"
 
 
 class ConditionType(Enum):