vellum-ai 1.7.6__py3-none-any.whl → 1.7.8__py3-none-any.whl

vellum/workflows/triggers/base.py

@@ -1,11 +1,58 @@
 from abc import ABC, ABCMeta
-from typing import TYPE_CHECKING, Any, Type, cast
+import inspect
+from typing import TYPE_CHECKING, Any, ClassVar, Dict, Iterator, Tuple, Type, cast, get_origin
 
 if TYPE_CHECKING:
     from vellum.workflows.graph.graph import Graph, GraphTarget
+    from vellum.workflows.state.base import BaseState
+
+from vellum.workflows.references.trigger import TriggerAttributeReference
+from vellum.workflows.types.utils import get_class_attr_names, infer_types
+from vellum.workflows.utils.uuids import uuid4_from_hash
+
+
+def _is_annotated(cls: Type, name: str) -> bool:
+    annotations = getattr(cls, "__annotations__", {})
+    annotation = annotations.get(name)
+    if annotation is not None:
+        if get_origin(annotation) is ClassVar:
+            return False
+        return True
+
+    for base in cls.__bases__:
+        if _is_annotated(base, name):
+            return True
+
+    return False
 
 
 class BaseTriggerMeta(ABCMeta):
+    def __new__(mcs, name: str, bases: Tuple[Type, ...], dct: Dict[str, Any]) -> Any:
+        cls = super().__new__(mcs, name, bases, dct)
+        trigger_cls = cast(Type["BaseTrigger"], cls)
+
+        attribute_ids: Dict[str, Any] = {}
+        for base in bases:
+            base_ids = getattr(base, "__trigger_attribute_ids__", None)
+            if isinstance(base_ids, dict):
+                attribute_ids.update(base_ids)
+
+        annotations = getattr(trigger_cls, "__annotations__", {})
+        for attr_name, annotation in annotations.items():
+            if attr_name.startswith("_"):
+                continue
+            if attr_name in trigger_cls.__dict__:
+                continue
+            if get_origin(annotation) is ClassVar:
+                continue
+            attribute_ids[attr_name] = uuid4_from_hash(
+                f"{trigger_cls.__module__}|{trigger_cls.__qualname__}|{attr_name}"
+            )
+
+        trigger_cls.__trigger_attribute_ids__ = attribute_ids
+        trigger_cls.__trigger_attribute_cache__ = {}
+        return trigger_cls
+
     """
     Metaclass for BaseTrigger that enables class-level >> operator.
 
@@ -13,6 +60,68 @@ class BaseTriggerMeta(ABCMeta):
         ManualTrigger >> MyNode  # Class-level, no instantiation
     """
 
+    def __getattribute__(cls, name: str) -> Any:
+        trigger_cls = cast(Type["BaseTrigger"], cls)
+        if name.startswith("_"):
+            return super().__getattribute__(name)
+
+        try:
+            attribute = super().__getattribute__(name)
+        except AttributeError as exc:
+            if _is_annotated(cls, name):
+                attribute = None
+            else:
+                raise exc
+
+        if inspect.isroutine(attribute) or isinstance(attribute, (property, classmethod, staticmethod)):
+            return attribute
+
+        if isinstance(attribute, TriggerAttributeReference):
+            return attribute
+
+        if name in cls.__dict__:
+            return attribute
+
+        if not _is_annotated(cls, name):
+            return attribute
+
+        cache = getattr(cls, "__trigger_attribute_cache__", {})
+        if name in cache:
+            return cache[name]
+
+        for base in cls.__mro__[1:]:
+            base_cache = getattr(base, "__trigger_attribute_cache__", None)
+            if base_cache and name in base_cache:
+                cache[name] = base_cache[name]
+                return base_cache[name]
+
+        types = infer_types(cls, name)
+        reference = TriggerAttributeReference(name=name, types=types, instance=attribute, trigger_class=trigger_cls)
+        cache[name] = reference
+        cls.__trigger_attribute_cache__ = cache
+        return reference
+
+    def __iter__(cls) -> Iterator[TriggerAttributeReference]:
+        cache = getattr(cls, "__trigger_attribute_cache__", {})
+        seen: Dict[str, TriggerAttributeReference] = dict(cache)
+
+        for base in cls.__mro__[1:]:
+            base_cache = getattr(base, "__trigger_attribute_cache__", None)
+            if not base_cache:
+                continue
+            for key, value in base_cache.items():
+                seen.setdefault(key, value)
+
+        for attr_name in get_class_attr_names(cls):
+            if attr_name in seen:
+                yield seen[attr_name]
+                continue
+
+            attr_value = getattr(cls, attr_name)
+            if isinstance(attr_value, TriggerAttributeReference):
+                seen[attr_name] = attr_value
+                yield attr_value
+
     def __rshift__(cls, other: "GraphTarget") -> "Graph":  # type: ignore[misc]
         """
         Enable Trigger class >> Node syntax (class-level only).
@@ -33,7 +142,7 @@ class BaseTriggerMeta(ABCMeta):
         from vellum.workflows.nodes.bases.base import BaseNode as BaseNodeClass
 
         # Cast cls to the proper type for TriggerEdge
-        trigger_cls = cast("Type[BaseTrigger]", cls)
+        trigger_cls = cast(Type["BaseTrigger"], cls)
 
         if isinstance(other, set):
             # Trigger >> {NodeA, NodeB}
@@ -122,4 +231,32 @@ class BaseTrigger(ABC, metaclass=BaseTriggerMeta):
         Like nodes, triggers work at the class level only. Do not instantiate triggers.
     """
 
-    pass
+    __trigger_attribute_ids__: Dict[str, Any]
+    __trigger_attribute_cache__: Dict[str, "TriggerAttributeReference[Any]"]
+
+    @classmethod
+    def attribute_references(cls) -> Dict[str, "TriggerAttributeReference[Any]"]:
+        """Return class-level trigger attribute descriptors keyed by attribute name."""
+
+        return {reference.name: reference for reference in cls}
+
+    def to_trigger_attribute_values(self) -> Dict["TriggerAttributeReference[Any]", Any]:
+        """Materialize attribute descriptor/value pairs for this trigger instance."""
+
+        attribute_values: Dict["TriggerAttributeReference[Any]", Any] = {}
+        for reference in type(self):
+            if hasattr(self, reference.name):
+                attribute_values[reference] = getattr(self, reference.name)
+            elif type(None) in reference.types:
+                attribute_values[reference] = None
+            else:
+                raise AttributeError(
+                    f"{type(self).__name__} did not populate required trigger attribute '{reference.name}'"
+                )
+
+        return attribute_values
+
+    def bind_to_state(self, state: "BaseState") -> None:
+        """Persist this trigger's attribute values onto the provided state."""
+
+        state.meta.trigger_attributes.update(self.to_trigger_attribute_values())

vellum/workflows/triggers/integration.py

@@ -1,7 +1,6 @@
 from abc import ABC
 from typing import ClassVar, Optional
 
-from vellum.workflows.outputs.base import BaseOutputs
 from vellum.workflows.triggers.base import BaseTrigger
 
 
@@ -11,52 +10,58 @@ class IntegrationTrigger(BaseTrigger, ABC):
 
     Integration triggers:
     - Are initiated by external events (webhooks, API calls)
-    - Produce outputs that downstream nodes can reference
+    - Produce attributes that downstream nodes can reference
     - Require configuration (auth, webhooks, etc.)
 
     Examples:
         # Define an integration trigger
         class MyIntegrationTrigger(IntegrationTrigger):
-            class Outputs(IntegrationTrigger.Outputs):
-                data: str
+            data: str
 
-            @classmethod
-            def process_event(cls, event_data: dict):
-                return cls.Outputs(data=event_data.get("data", ""))
+            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 outputs
-        that downstream nodes can reference directly via Outputs.
+        Unlike ManualTrigger, integration triggers provide structured attributes
+        that downstream nodes can reference directly.
     """
 
-    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":
+    def __init__(self, event_data: dict):
         """
-        Process incoming webhook/event data and return trigger outputs.
+        Initialize trigger with event data from external system.
 
-        This method should be implemented by subclasses to parse external
-        event payloads (e.g., Slack webhooks, email notifications) into
-        structured trigger outputs.
+        Subclasses should override this method to parse external
+        event payloads (e.g., Slack webhooks, email notifications) and
+        populate trigger attributes.
 
         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
+        Examples:
+            >>> class MyTrigger(IntegrationTrigger):
+            ...     data: 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'
         """
-        raise NotImplementedError(f"{cls.__name__} must implement process_event() method to handle external events")
+        self._event_data = event_data

vellum/workflows/triggers/slack.py

@@ -0,0 +1,101 @@
+from typing import Optional
+
+from vellum.workflows.triggers.integration import IntegrationTrigger
+
+
+class SlackTrigger(IntegrationTrigger):
+    """
+    Trigger for Slack events (messages, mentions, reactions, etc.).
+
+    SlackTrigger enables workflows to be initiated from Slack events such as
+    messages in channels, direct messages, app mentions, or reactions. The trigger
+    parses Slack webhook payloads and provides structured attributes that downstream
+    nodes can reference.
+
+    Examples:
+        Basic Slack message trigger:
+            >>> class MyWorkflow(BaseWorkflow):
+            ...     graph = SlackTrigger >> ProcessMessageNode
+
+        Access trigger attributes in nodes:
+            >>> class ProcessMessageNode(BaseNode):
+            ...     class Outputs(BaseNode.Outputs):
+            ...         response = SlackTrigger.message
+
+        Multiple entry points:
+            >>> class MyWorkflow(BaseWorkflow):
+            ...     graph = {
+            ...         SlackTrigger >> ProcessSlackNode,
+            ...         ManualTrigger >> ProcessManualNode,
+            ...     }
+
+    Attributes:
+        message: str
+            The message text from Slack
+        channel: str
+            Slack channel ID where message was sent
+        user: str
+            User ID who sent the message
+        timestamp: str
+            Message timestamp (ts field from Slack)
+        thread_ts: Optional[str]
+            Thread timestamp if message is in a thread, None otherwise
+        event_type: str
+            Type of Slack event (e.g., "message", "app_mention")
+
+    Note:
+        The trigger expects Slack Event API webhook payloads. For details on
+        the payload structure, see: https://api.slack.com/apis/connections/events-api
+    """
+
+    message: str
+    channel: str
+    user: str
+    timestamp: str
+    thread_ts: Optional[str]
+    event_type: str
+
+    def __init__(self, event_data: dict):
+        """
+        Initialize SlackTrigger with Slack webhook payload.
+
+        Args:
+            event_data: Slack event payload from webhook. Expected structure:
+                {
+                    "event": {
+                        "type": "message",
+                        "text": "Hello world",
+                        "channel": "C123456",
+                        "user": "U123456",
+                        "ts": "1234567890.123456",
+                        "thread_ts": "1234567890.123456"  # optional
+                    }
+                }
+
+        Examples:
+            >>> slack_payload = {
+            ...     "event": {
+            ...         "type": "message",
+            ...         "text": "Hello!",
+            ...         "channel": "C123",
+            ...         "user": "U456",
+            ...         "ts": "1234567890.123456"
+            ...     }
+            ... }
+            >>> trigger = SlackTrigger(slack_payload)
+            >>> trigger.message
+            'Hello!'
+        """
+        # Call parent init
+        super().__init__(event_data)
+
+        # Extract from Slack's event structure
+        event = event_data.get("event", {})
+
+        # Populate trigger attributes
+        self.message = event.get("text", "")
+        self.channel = event.get("channel", "")
+        self.user = event.get("user", "")
+        self.timestamp = event.get("ts", "")
+        self.thread_ts = event.get("thread_ts")
+        self.event_type = event.get("type", "message")

vellum/workflows/triggers/tests/test_integration.py

@@ -1,24 +1,29 @@
 """Tests for IntegrationTrigger base class."""
 
-import pytest
-
 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__is_abstract():
-    """IntegrationTrigger cannot be instantiated directly (ABC)."""
-    # WHEN we try to call process_event on IntegrationTrigger directly
-    # THEN it raises NotImplementedError
-    with pytest.raises(NotImplementedError, match="must implement process_event"):
-        IntegrationTrigger.process_event({})
+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__outputs_class_exists():
-    """IntegrationTrigger has Outputs class."""
-    # GIVEN IntegrationTrigger
-    # THEN it has an Outputs class
-    assert hasattr(IntegrationTrigger, "Outputs")
+
+def test_integration_trigger__can_be_instantiated():
+    """IntegrationTrigger can be instantiated for testing."""
+
+    # GIVEN IntegrationTrigger with concrete implementation
+    class TestTrigger(IntegrationTrigger):
+        pass
+
+    # 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():
@@ -26,31 +31,51 @@ def test_integration_trigger__can_be_subclassed():
 
     # GIVEN a concrete implementation of IntegrationTrigger
     class TestTrigger(IntegrationTrigger):
-        class Outputs(IntegrationTrigger.Outputs):
-            data: str
+        data: str
 
-        @classmethod
-        def process_event(cls, event_data: dict):
-            return cls.Outputs(data=event_data.get("data", ""))
+        def __init__(self, event_data: dict):
+            super().__init__(event_data)
+            self.data = event_data.get("data", "")
 
-    # WHEN we process an event
-    result = TestTrigger.process_event({"data": "test"})
+    # WHEN we create a trigger instance
+    result = TestTrigger({"data": "test"})
 
-    # THEN it returns the expected outputs
+    # 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
+
+        def __init__(self, event_data: dict):
+            super().__init__(event_data)
+            self.value = event_data.get("value", "")
+
+    reference = TestTrigger.value
+    assert isinstance(reference, TriggerAttributeReference)
+    assert reference.name == "value"
+    assert TestTrigger.value is reference
+    assert reference is 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):
-        class Outputs(IntegrationTrigger.Outputs):
-            value: str
+        value: str
 
-        @classmethod
-        def process_event(cls, event_data: dict):
-            return cls.Outputs(value=event_data.get("value", ""))
+        def __init__(self, event_data: dict):
+            super().__init__(event_data)
+            self.value = event_data.get("value", "")
 
     class TestNode(BaseNode):
         pass
@@ -70,12 +95,11 @@ def test_integration_trigger__multiple_entrypoints():
 
     # GIVEN a trigger and multiple nodes
     class TestTrigger(IntegrationTrigger):
-        class Outputs(IntegrationTrigger.Outputs):
-            msg: str
+        msg: str
 
-        @classmethod
-        def process_event(cls, event_data: dict):
-            return cls.Outputs(msg=event_data.get("msg", ""))
+        def __init__(self, event_data: dict):
+            super().__init__(event_data)
+            self.msg = event_data.get("msg", "")
 
     class NodeA(BaseNode):
         pass

vellum/workflows/triggers/tests/test_slack.py

@@ -0,0 +1,180 @@
+"""Tests for SlackTrigger."""
+
+from typing import cast
+
+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.slack import SlackTrigger
+
+
+def test_slack_trigger__basic():
+    """SlackTrigger parses Slack payload correctly."""
+    # GIVEN a Slack event payload
+    slack_payload = {
+        "event": {
+            "type": "message",
+            "text": "Hello world!",
+            "channel": "C123456",
+            "user": "U123456",
+            "ts": "1234567890.123456",
+        }
+    }
+
+    # WHEN we create a trigger instance
+    trigger = SlackTrigger(slack_payload)
+
+    # THEN trigger attributes contain the correct data
+    assert trigger.message == "Hello world!"
+    assert trigger.channel == "C123456"
+    assert trigger.user == "U123456"
+    assert trigger.timestamp == "1234567890.123456"
+    assert trigger.thread_ts is None
+    assert trigger.event_type == "message"
+
+    # AND the trigger can bind values to workflow state
+    state = BaseState()
+    trigger.bind_to_state(state)
+    stored = state.meta.trigger_attributes
+    message_ref = cast(TriggerAttributeReference[str], SlackTrigger.message)
+    assert message_ref in stored
+    assert stored[message_ref] == "Hello world!"
+
+
+def test_slack_trigger__with_thread():
+    """SlackTrigger handles threaded messages."""
+    # GIVEN a Slack event payload with thread_ts
+    slack_payload = {
+        "event": {
+            "type": "message",
+            "text": "Reply in thread",
+            "channel": "C123456",
+            "user": "U123456",
+            "ts": "1234567891.123456",
+            "thread_ts": "1234567890.123456",
+        }
+    }
+
+    # WHEN we create a trigger instance
+    trigger = SlackTrigger(slack_payload)
+
+    # THEN thread_ts is populated
+    assert trigger.thread_ts == "1234567890.123456"
+
+
+def test_slack_trigger__empty_payload():
+    """SlackTrigger handles empty payload gracefully."""
+    # GIVEN an empty payload
+    slack_payload: dict[str, str] = {}
+
+    # WHEN we create a trigger instance
+    trigger = SlackTrigger(slack_payload)
+
+    # THEN it returns empty strings for required fields
+    assert trigger.message == ""
+    assert trigger.channel == ""
+    assert trigger.user == ""
+    assert trigger.timestamp == ""
+    assert trigger.thread_ts is None
+    assert trigger.event_type == "message"  # default value
+
+
+def test_slack_trigger__app_mention():
+    """SlackTrigger handles app_mention events."""
+    # GIVEN an app_mention event
+    slack_payload = {
+        "event": {
+            "type": "app_mention",
+            "text": "<@U0LAN0Z89> is it everything a river should be?",
+            "channel": "C123456",
+            "user": "U123456",
+            "ts": "1234567890.123456",
+        }
+    }
+
+    # WHEN we create a trigger instance
+    trigger = SlackTrigger(slack_payload)
+
+    # THEN event_type is app_mention
+    assert trigger.event_type == "app_mention"
+    assert trigger.message == "<@U0LAN0Z89> is it everything a river should be?"
+
+
+def test_slack_trigger__attributes():
+    """SlackTrigger has correct attributes."""
+    # GIVEN SlackTrigger class
+    # THEN it exposes attribute references for annotated fields
+    reference = SlackTrigger.message
+    assert isinstance(reference, TriggerAttributeReference)
+    assert reference.name == "message"
+    assert SlackTrigger.message is reference  # cache returns same reference
+
+    annotations = SlackTrigger.__annotations__
+    assert set(annotations) >= {"message", "channel", "user", "timestamp", "thread_ts", "event_type"}
+
+    # AND references resolve when present on state
+    state = BaseState()
+    state.meta.trigger_attributes[reference] = "Hello"
+    assert reference.resolve(state) == "Hello"
+
+
+def test_slack_trigger__graph_syntax():
+    """SlackTrigger can be used in graph syntax."""
+
+    # GIVEN a node
+    class TestNode(BaseNode):
+        pass
+
+    # WHEN we use SlackTrigger >> Node syntax
+    graph = SlackTrigger >> TestNode
+
+    # THEN a graph is created with trigger edge
+    assert graph is not None
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 1
+    assert trigger_edges[0].trigger_class == SlackTrigger
+    assert trigger_edges[0].to_node == TestNode
+
+
+def test_slack_trigger__multiple_entrypoints():
+    """SlackTrigger works with multiple entry points."""
+
+    # GIVEN multiple nodes
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    # WHEN we use SlackTrigger >> {NodeA, NodeB} syntax
+    graph = SlackTrigger >> {NodeA, NodeB}
+
+    # THEN both nodes have trigger edges
+    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_slack_trigger__trigger_then_graph():
+    """SlackTrigger works with trigger >> node >> node syntax."""
+
+    # GIVEN two nodes
+    class StartNode(BaseNode):
+        pass
+
+    class EndNode(BaseNode):
+        pass
+
+    # WHEN we create SlackTrigger >> StartNode >> EndNode
+    graph = SlackTrigger >> StartNode >> EndNode
+
+    # THEN the graph has one trigger edge and one regular edge
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 1
+    assert trigger_edges[0].trigger_class == SlackTrigger
+    assert trigger_edges[0].to_node == StartNode
+
+    edges = list(graph.edges)
+    assert len(edges) == 1
+    assert edges[0].to_node == EndNode

{vellum_ai-1.7.6.dist-info → vellum_ai-1.7.8.dist-info}/METADATA

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