vellum-ai 1.8.5__py3-none-any.whl → 1.9.0__py3-none-any.whl

vellum/workflows/triggers/integration.py

@@ -1,67 +1,186 @@
 from abc import ABC
-from typing import ClassVar, Optional
+from typing import Any, ClassVar, Dict
 
-from vellum.workflows.triggers.base import BaseTrigger
+from vellum.workflows.constants import VellumIntegrationProviderType
+from vellum.workflows.references.trigger import TriggerAttributeReference
+from vellum.workflows.triggers.base import BaseTrigger, BaseTriggerMeta
 
 
-class IntegrationTrigger(BaseTrigger, ABC):
+class IntegrationTriggerMeta(BaseTriggerMeta):
     """
-    Base class for integration-based triggers (Slack, Email, etc.).
+    Custom metaclass for IntegrationTrigger.
 
-    Integration triggers:
-    - Are initiated by external events (webhooks, API calls)
-    - Produce attributes that downstream nodes can reference
-    - Require configuration (auth, webhooks, etc.)
+    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:
-        # Define an integration trigger
-        class MyIntegrationTrigger(IntegrationTrigger):
-            data: str
-
-            def __init__(self, event_data: dict):
-                super().__init__(event_data)
-                self.data = event_data.get("data", "")
-
-        # Use in workflow
-        class MyWorkflow(BaseWorkflow):
-            graph = MyIntegrationTrigger >> ProcessNode
-
-        # Reference trigger attributes in nodes
-        class ProcessNode(BaseNode):
-            class Outputs(BaseNode.Outputs):
-                result = MyIntegrationTrigger.data
-
-    Note:
-        Unlike ManualTrigger, integration triggers provide structured attributes
-        that downstream nodes can reference directly.
+        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'
     """
 
-    # Configuration that can be set at runtime
-    config: ClassVar[Optional[dict]] = None
+    class Config:
+        """
+        Configuration for IntegrationTrigger subclasses.
 
-    def __init__(self, event_data: dict):
+        Defines how the trigger connects to the integration provider. These settings
+        specify which integration and which specific trigger type to use.
         """
-        Initialize trigger with event data from external system.
 
-        Subclasses should override this method to parse external
-        event payloads (e.g., Slack webhooks, email notifications) and
-        populate trigger attributes.
+        provider: ClassVar[VellumIntegrationProviderType]
+        integration_name: ClassVar[str]
+        slug: ClassVar[str]
 
-        Args:
-            event_data: Raw event data from the external system
+    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 MyTrigger(IntegrationTrigger):
-            ...     data: str
+            >>> class SlackTrigger(IntegrationTrigger):
+            ...     message: str
+            ...     channel: str
+            ...     user: str
             ...
-            ...     def __init__(self, event_data: dict):
-            ...         super().__init__(event_data)
-            ...         self.data = event_data.get("data", "")
-            >>>
-            >>> trigger = MyTrigger({"data": "hello"})
-            >>> state = workflow.get_default_state()
-            >>> trigger.bind_to_state(state)
-            >>> MyTrigger.data.resolve(state)
-            'hello'
+            ...     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'
         """
-        self._event_data = event_data
+        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/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/test_integration.py

@@ -1,5 +1,8 @@
 """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
@@ -9,7 +12,7 @@ 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"})
+    trigger = IntegrationTrigger(test="data")
 
     # THEN it creates an instance with event data stored
     assert trigger._event_data == {"test": "data"}
@@ -20,7 +23,10 @@ def test_integration_trigger__can_be_instantiated():
 
     # GIVEN IntegrationTrigger with concrete implementation
     class TestTrigger(IntegrationTrigger):
-        pass
+        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
@@ -33,12 +39,17 @@ def test_integration_trigger__can_be_subclassed():
     class TestTrigger(IntegrationTrigger):
         data: str
 
-        def __init__(self, event_data: dict):
-            super().__init__(event_data)
-            self.data = event_data.get("data", "")
+        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"})
+    result = TestTrigger(data="test")
 
     # THEN it returns the expected trigger instance with populated attributes
     assert result.data == "test"
@@ -50,9 +61,14 @@ def test_integration_trigger__attribute_reference():
     class TestTrigger(IntegrationTrigger):
         value: str
 
-        def __init__(self, event_data: dict):
-            super().__init__(event_data)
-            self.value = event_data.get("value", "")
+        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)
@@ -61,7 +77,7 @@ def test_integration_trigger__attribute_reference():
     assert reference == TestTrigger.attribute_references()["value"]
 
     state = BaseState()
-    trigger = TestTrigger({"value": "data"})
+    trigger = TestTrigger(value="data")
     trigger.bind_to_state(state)
     assert reference.resolve(state) == "data"
 
@@ -73,9 +89,14 @@ def test_integration_trigger__graph_syntax():
     class TestTrigger(IntegrationTrigger):
         value: str
 
-        def __init__(self, event_data: dict):
-            super().__init__(event_data)
-            self.value = event_data.get("value", "")
+        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
@@ -97,9 +118,14 @@ def test_integration_trigger__multiple_entrypoints():
     class TestTrigger(IntegrationTrigger):
         msg: str
 
-        def __init__(self, event_data: dict):
-            super().__init__(event_data)
-            self.msg = event_data.get("msg", "")
+        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
@@ -118,9 +144,12 @@ def test_integration_trigger__multiple_entrypoints():
 
 
 def test_integration_trigger__config_attribute():
-    """IntegrationTrigger has optional config attribute."""
+    """IntegrationTrigger requires Config class with provider, integration_name, and slug."""
 
     # GIVEN IntegrationTrigger
-    # THEN it has a config class variable
-    assert hasattr(IntegrationTrigger, "config")
-    assert IntegrationTrigger.config is None
+    # 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/utils/uuids.py

@@ -43,20 +43,6 @@ def uuid4_from_hash(input_str: str) -> UUID:
     return UUID(bytes=bytes(hash_list))
 
 
-def get_trigger_id(trigger_class: "type[BaseTrigger]") -> UUID:
-    """
-    Generate a deterministic trigger ID from a trigger class using
-    the class's module name and __qualname__ to ensure stability and uniqueness.
-
-    Args:
-        trigger_class: The trigger class to generate an ID for
-
-    Returns:
-        A deterministic UUID based on the trigger class module and qualname
-    """
-    return uuid4_from_hash(f"{trigger_class.__module__}.{trigger_class.__qualname__}")
-
-
 def get_trigger_attribute_id(trigger_class: "type[BaseTrigger]", attribute_name: str) -> UUID:
     """
     Generate a deterministic trigger attribute ID from a trigger class and attribute name
@@ -69,5 +55,5 @@ def get_trigger_attribute_id(trigger_class: "type[BaseTrigger]", attribute_name:
     Returns:
         A deterministic UUID based on the trigger class module, qualname, and attribute name
     """
-    trigger_id = get_trigger_id(trigger_class)
+    trigger_id = trigger_class.__id__
     return uuid4_from_hash(f"{trigger_id}|{attribute_name}")

vellum/workflows/workflows/base.py

@@ -714,6 +714,50 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
 
         return state_class(**state)
 
+    @classmethod
+    def deserialize_trigger(cls, trigger_id: Optional[UUID], inputs: dict) -> Union[InputsType, BaseTrigger]:
+        """
+        Deserialize a trigger from a trigger_id and inputs dict.
+
+        If trigger_id is None, returns an instance of the workflow's Inputs class.
+        Otherwise, finds a trigger class that matches the trigger_id and creates an instance of that.
+
+        Parameters
+        ----------
+        trigger_id: Optional[UUID]
+            The UUID of the trigger class to instantiate. If None, returns workflow Inputs.
+
+        inputs: dict
+            The inputs to pass to the trigger or Inputs constructor.
+
+        Returns
+        -------
+        Union[InputsType, BaseTrigger]
+            Either an instance of the workflow's Inputs class (if trigger_id is None)
+            or an instance of the matching trigger class.
+
+        Raises
+        ------
+        WorkflowInitializationException
+            If trigger_id is provided but no matching trigger class is found in the workflow.
+        """
+        if trigger_id is None:
+            inputs_class = cls.get_inputs_class()
+            return inputs_class(**inputs)
+
+        trigger_classes = []
+        for subgraph in cls.get_subgraphs():
+            for trigger_class in subgraph.triggers:
+                if trigger_class.__id__ == trigger_id:
+                    return trigger_class(**inputs)
+
+                trigger_classes.append(trigger_class)
+
+        raise WorkflowInitializationException(
+            message=f"No trigger class found with id {trigger_id} in workflow {cls.__name__}. "
+            f"Available trigger classes: {[trigger_class.__name__ for trigger_class in trigger_classes]}"
+        )
+
     @staticmethod
     def load_from_module(module_path: str) -> Type["BaseWorkflow"]:
         workflow_path = f"{module_path}.workflow"

{vellum_ai-1.8.5.dist-info → vellum_ai-1.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vellum-ai
-Version: 1.8.5
+Version: 1.9.0
 Summary: 
 License: MIT
 Requires-Python: >=3.9,<4.0