vellum-ai 1.7.11__py3-none-any.whl → 1.7.13__py3-none-any.whl

vellum/workflows/triggers/vellum_integration.py

@@ -1,163 +1,141 @@
 import json
-from typing import Any, ClassVar, Dict, Optional, Type, cast
+from typing import Any, ClassVar, Dict, Optional, Type
 
 from vellum.workflows.constants import VellumIntegrationProviderType
 from vellum.workflows.references.trigger import TriggerAttributeReference
 from vellum.workflows.triggers.base import BaseTriggerMeta
 from vellum.workflows.triggers.integration import IntegrationTrigger
 from vellum.workflows.types import ComposioIntegrationTriggerExecConfig
-from vellum.workflows.utils.uuids import uuid4_from_hash
 
 
 class VellumIntegrationTriggerMeta(BaseTriggerMeta):
     """
-    Custom metaclass for VellumIntegrationTrigger that supports dynamic attribute discovery.
-
-    This metaclass extends BaseTriggerMeta to enable class-level access to attributes
-    that aren't statically defined. When accessing an undefined attribute on a
-    VellumIntegrationTrigger class, this metaclass will create a TriggerAttributeReference
-    dynamically, allowing triggers to work with attributes discovered from integration
-    APIs or event payloads.
-
-    Note: This metaclass intentionally deviates from the standard metaclass pattern used
-    in BaseNodeMeta and BaseWorkflowMeta, which generate nested classes (Outputs, Inputs)
-    in __new__. Since VellumIntegrationTrigger uses a factory pattern with dynamic
-    attributes rather than predefined nested classes, this metaclass focuses on
-    attribute discovery via __getattribute__ during workflow definition (when the
-    developer references trigger attributes in their workflow code) instead of class
-    generation in __new__. This architectural difference is necessary to support the
-    dynamic nature of integration triggers where attributes are not known until the
-    integration is queried or event data is received.
-    """
+    Custom metaclass for VellumIntegrationTrigger.
 
-    def __getattribute__(cls, name: str) -> Any:
-        """
-        Override attribute access to support dynamic attribute discovery.
+    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.
+    """
 
-        For VellumIntegrationTrigger classes generated by the factory, this method
-        allows access to any attribute name, creating TriggerAttributeReference objects
-        on demand. This enables usage like:
+    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any) -> "VellumIntegrationTriggerMeta":
+        """Create a new trigger class and set up attribute references."""
+        cls = super().__new__(mcs, name, bases, namespace, **kwargs)
 
-            SlackMessage = VellumIntegrationTrigger.for_trigger(
-                integration_name="SLACK",
-                slug="slack_new_message",
-                trigger_nano_id="abc123"
-            )
-            text = SlackMessage.message  # Creates reference even though 'message' isn't pre-defined
+        # 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
 
-        Args:
-            name: The attribute name being accessed
+                # 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)
 
-        Returns:
-            The attribute value or a dynamically created TriggerAttributeReference
-        """
-        # Let BaseTriggerMeta handle internal attributes and known attributes
-        try:
-            return super().__getattribute__(name)
-        except AttributeError:
-            # For VellumIntegrationTrigger factory-generated classes, create dynamic references
-            # Only enable dynamic attribute creation for factory-generated classes, not the base
-            # VellumIntegrationTrigger class itself. We check the internal __name__ attribute
-            # (e.g., "VellumIntegrationTrigger_COMPOSIO_SLACK_slack_new_message"), not the user-facing
-            # variable name (e.g., "SlackNewMessage").
-            try:
-                is_factory_class = super().__getattribute__("__name__").startswith(
-                    "VellumIntegrationTrigger_"
-                ) and not name.startswith("_")
-            except AttributeError:
-                is_factory_class = False
-
-            if is_factory_class:
-                trigger_cls = cast(Type["VellumIntegrationTrigger"], cls)
-
-                # Check cache first
-                cache = super().__getattribute__("__trigger_attribute_cache__")
-                if name in cache:
-                    return cache[name]
-
-                # Generate and store deterministic UUID for this attribute if not already present.
-                # This ensures consistent IDs across multiple accesses to the same attribute,
-                # which is critical for serialization and state resolution.
-                # Use semantic identity (provider|integration|slug) instead of __qualname__ for stability.
-                attribute_ids = super().__getattribute__("__trigger_attribute_ids__")
-                if name not in attribute_ids:
-                    # Generate stable ID from trigger semantics, not class naming
-                    provider = super().__getattribute__("provider")
-                    integration_name = super().__getattribute__("integration_name")
-                    slug = super().__getattribute__("slug")
-                    trigger_identity = f"{provider.value}|{integration_name}|{slug}"
-                    attribute_ids[name] = uuid4_from_hash(f"{trigger_identity}|{name}")
-
-                # Create a new dynamic reference for this attribute
-                types = (object,)
-                reference = TriggerAttributeReference(name=name, types=types, instance=None, trigger_class=trigger_cls)
-                cache[name] = reference
-                return reference
-
-            # Not a factory class or starts with _, re-raise the AttributeError
-            raise
+        return cls
 
 
 class VellumIntegrationTrigger(IntegrationTrigger, metaclass=VellumIntegrationTriggerMeta):
     """
-    Factory-based trigger for Vellum-managed integration events.
+    Base class for Vellum-managed integration triggers.
 
-    VellumIntegrationTrigger provides a pure factory pattern for creating trigger
-    classes dynamically based on integration provider, integration name, slug, and
-    trigger nano ID. Unlike predefined trigger classes, these triggers are created
-    on-demand and support dynamic attribute discovery from the integration API.
-
-    This design ensures parity with VellumIntegrationToolDefinition and allows users to
-    work with any integration trigger without requiring SDK updates for new integrations.
+    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 triggers dynamically for different integrations:
-            >>> SlackNewMessage = VellumIntegrationTrigger.for_trigger(
-            ...     integration_name="SLACK",
-            ...     slug="slack_new_message",
-            ...     trigger_nano_id="abc123def456"
-            ... )
-            >>>
-            >>> GithubPush = VellumIntegrationTrigger.for_trigger(
-            ...     integration_name="GITHUB",
-            ...     slug="github_push_event",
-            ...     trigger_nano_id="xyz789ghi012"
-            ... )
+        Create a Slack trigger:
+            >>> class SlackNewMessageTrigger(VellumIntegrationTrigger):
+            ...     # Event attributes (webhook payload structure)
+            ...     message: str
+            ...     user: str
+            ...     channel: str
+            ...     timestamp: float
+            ...
+            ...     # Configuration (how trigger is set up)
+            ...     class Config(VellumIntegrationTrigger.Config):
+            ...         provider = VellumIntegrationProviderType.COMPOSIO
+            ...         integration_name = "SLACK"
+            ...         slug = "slack_new_message"
 
         Use in workflow graph:
             >>> class MyWorkflow(BaseWorkflow):
-            ...     graph = SlackNewMessage >> ProcessMessageNode
+            ...     graph = SlackNewMessageTrigger >> ProcessMessageNode
 
         Reference trigger attributes in nodes:
             >>> class ProcessNode(BaseNode):
             ...     class Outputs(BaseNode.Outputs):
-            ...         text = SlackNewMessage.message
-            ...         channel = SlackNewMessage.channel
+            ...         text = SlackNewMessageTrigger.message
+            ...         channel = SlackNewMessageTrigger.channel
 
         Instantiate for testing:
-            >>> trigger = SlackNewMessage(event_data={
+            >>> trigger = SlackNewMessageTrigger(event_data={
             ...     "message": "Hello world",
-            ...     "channel": "C123456"
+            ...     "channel": "C123456",
+            ...     "user": "U123",
+            ...     "timestamp": 1234567890.0,
             ... })
             >>> trigger.message
             'Hello world'
-
-    Note:
-        The factory method generates unique classes with proper __name__ and __module__
-        for correct attribute ID generation and serialization. Each factory call with
-        the same parameters returns the same class instance (cached).
     """
 
-    # Class variables that identify this trigger
-    provider: ClassVar[VellumIntegrationProviderType]
-    integration_name: ClassVar[str]
-    slug: ClassVar[str]
-    trigger_nano_id: ClassVar[str]
-    attributes: ClassVar[Dict[str, Any]]
+    class Config:
+        """
+        Configuration for VellumIntegrationTrigger 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]
 
     # Cache for generated trigger classes to ensure consistency
     _trigger_class_cache: ClassVar[Dict[tuple, Type["VellumIntegrationTrigger"]]] = {}
 
+    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__ == "VellumIntegrationTrigger":
+            return
+
+        # Skip validation for dynamically created classes (they use dynamic attributes)
+        if cls.__name__.startswith("VellumIntegrationTrigger_"):
+            return
+
+        # Require Config class with required fields
+        if not hasattr(cls, "Config") or cls.Config is VellumIntegrationTrigger.Config:
+            raise TypeError(
+                f"{cls.__name__} must define a nested Config class. "
+                f"Example:\n"
+                f"  class {cls.__name__}(VellumIntegrationTrigger):\n"
+                f"      message: str\n"
+                f"      class Config(VellumIntegrationTrigger.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)}"
+                )
+
     @classmethod
     def _freeze_attributes(cls, attributes: Dict[str, Any]) -> str:
         """
@@ -236,9 +214,10 @@ class VellumIntegrationTrigger(IntegrationTrigger, metaclass=VellumIntegrationTr
         # 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
-            # This will create it via our custom metaclass if it doesn't exist
-            reference = getattr(type(self), attr_name)
+            # 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)
 
@@ -250,39 +229,52 @@ class VellumIntegrationTrigger(IntegrationTrigger, metaclass=VellumIntegrationTr
         Generate execution configuration for serialization.
 
         This method creates a ComposioIntegrationTriggerExecConfig from the trigger
-        class's configuration, which is used during serialization to the backend.
+        class's configuration (from Config class) and event attributes (from top-level
+        type annotations), which is used during serialization to the backend.
 
         Returns:
-            ComposioIntegrationTriggerExecConfig with all required fields
+            ComposioIntegrationTriggerExecConfig with configuration and event attribute schema
 
         Raises:
-            AttributeError: If called on base VellumIntegrationTrigger (not factory class)
+            AttributeError: If called on base VellumIntegrationTrigger
 
         Examples:
-            >>> SlackMessage = VellumIntegrationTrigger.for_trigger(
-            ...     integration_name="SLACK",
-            ...     slug="slack_new_message",
-            ...     trigger_nano_id="abc123",
-            ...     attributes={"channel": "C123456"}
-            ... )
-            >>> exec_config = SlackMessage.to_exec_config()
+            >>> class SlackTrigger(VellumIntegrationTrigger):
+            ...     # Event attributes
+            ...     message: str
+            ...     user: str
+            ...
+            ...     # Configuration
+            ...     class Config(VellumIntegrationTrigger.Config):
+            ...         provider = VellumIntegrationProviderType.COMPOSIO
+            ...         integration_name = "SLACK"
+            ...         slug = "slack_new_message"
+            >>> exec_config = SlackTrigger.to_exec_config()
             >>> exec_config.slug
             'slack_new_message'
-            >>> exec_config.attributes
-            {'channel': 'C123456'}
+            >>> exec_config.event_attributes
+            {'message': <class 'str'>, 'user': <class 'str'>}
         """
-        if not hasattr(cls, "slug"):
+        if not hasattr(cls, "Config") or cls.Config is VellumIntegrationTrigger.Config:
             raise AttributeError(
-                "to_exec_config() can only be called on factory-generated trigger classes. "
-                "Use VellumIntegrationTrigger.for_trigger() to create a trigger class first."
+                "to_exec_config() can only be called on configured VellumIntegrationTrigger subclasses, "
+                "not on the base class."
             )
 
+        # Build event_attributes from annotations
+        event_attributes: Dict[str, Any] = {}
+        if hasattr(cls, "__annotations__"):
+            event_attributes = {
+                name: type_
+                for name, type_ in cls.__annotations__.items()
+                if not name.startswith("_") and name != "Config"
+            }
+
         return ComposioIntegrationTriggerExecConfig(
-            provider=cls.provider,
-            integration_name=cls.integration_name,
-            slug=cls.slug,
-            trigger_nano_id=cls.trigger_nano_id,
-            attributes=cls.attributes,
+            provider=cls.Config.provider,
+            integration_name=cls.Config.integration_name,
+            slug=cls.Config.slug,
+            event_attributes=event_attributes,
         )
 
     @classmethod

vellum/workflows/types/trigger_exec_config.py

@@ -6,7 +6,7 @@ sent to/from the backend for integration triggers. They are used during
 serialization and deserialization of trigger configurations.
 """
 
-from typing import Any, Dict, Literal, Optional
+from typing import Any, Dict, Literal
 
 from pydantic import Field
 
@@ -31,33 +31,30 @@ class ComposioIntegrationTriggerExecConfig(BaseIntegrationTriggerExecConfig):
 
     This configuration is used to identify and execute triggers through the Composio
     integration provider. It includes the provider type, integration name, slug,
-    trigger nano ID, and optional attributes for filtering.
+    trigger nano ID, and event schema.
 
     Examples:
         >>> config = ComposioIntegrationTriggerExecConfig(
         ...     provider="COMPOSIO",
         ...     integration_name="SLACK",
         ...     slug="slack_new_message",
-        ...     trigger_nano_id="abc123def456",
-        ...     attributes={"channel": "C123456"}
+        ...     event_attributes={"message": str, "user": str}
         ... )
         >>> config.provider
         <VellumIntegrationProviderType.COMPOSIO: 'COMPOSIO'>
 
     Attributes:
-        type: Always "COMPOSIO_INTEGRATION_TRIGGER" for this config type
+        type: Always "INTEGRATION" for this config type
         provider: The integration provider (e.g., COMPOSIO)
         integration_name: The integration identifier (e.g., "SLACK", "GITHUB")
         slug: The slug of the integration trigger in Composio
-        trigger_nano_id: Composio's unique trigger identifier used for event matching
-        attributes: Optional dictionary of trigger-specific configuration attributes for filtering
+        event_attributes: Dictionary mapping attribute names to their types (schema for event data)
     """
 
-    type: Literal["COMPOSIO_INTEGRATION_TRIGGER"] = "COMPOSIO_INTEGRATION_TRIGGER"
+    type: Literal["INTEGRATION"] = "INTEGRATION"
     provider: VellumIntegrationProviderType = Field(..., description="The integration provider (e.g., COMPOSIO)")
     integration_name: str = Field(..., description="The integration name (e.g., 'SLACK', 'GITHUB')")
     slug: str = Field(..., description="The slug of the integration trigger in Composio")
-    trigger_nano_id: str = Field(..., description="Composio's unique trigger identifier used for event matching")
-    attributes: Optional[Dict[str, Any]] = Field(
-        default=None, description="Optional trigger-specific configuration attributes for filtering"
+    event_attributes: Dict[str, Any] = Field(
+        default_factory=dict, description="Schema of event attributes with their types"
     )

vellum/workflows/utils/uuids.py

@@ -1,5 +1,9 @@
 import hashlib
 from uuid import UUID
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from vellum.workflows.triggers.base import BaseTrigger
 
 
 def generate_workflow_deployment_prefix(deployment_name: str, release_tag: str) -> str:
@@ -37,3 +41,32 @@ def uuid4_from_hash(input_str: str) -> UUID:
 
     # Create a UUID from the modified bytes
     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 __qualname__ to ensure stability across different import paths.
+
+    Args:
+        trigger_class: The trigger class to generate an ID for
+
+    Returns:
+        A deterministic UUID based on the trigger class qualname
+    """
+    return uuid4_from_hash(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
+    using the class's __qualname__ and attribute name to ensure stability.
+
+    Args:
+        trigger_class: The trigger class containing the attribute
+        attribute_name: The name of the attribute
+
+    Returns:
+        A deterministic UUID based on the trigger class qualname and attribute name
+    """
+    return uuid4_from_hash(f"{trigger_class.__qualname__}|{attribute_name}")

{vellum_ai-1.7.11.dist-info → vellum_ai-1.7.13.dist-info}/METADATA

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