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

vellum/workflows/triggers/base.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Any, ClassVar, Dict, Iterator, Optional, Tuple
 from vellum.workflows.references.trigger import TriggerAttributeReference
 from vellum.workflows.types.utils import get_class_attr_names, infer_types
 from vellum.workflows.utils.files import virtual_open
-from vellum.workflows.utils.uuids import uuid4_from_hash
+from vellum.workflows.utils.uuids import get_trigger_attribute_id, uuid4_from_hash
 from vellum_ee.workflows.display.editor import NodeDisplayComment
 
 if TYPE_CHECKING:
@@ -53,6 +53,37 @@ def _convert_to_relative_module_path(absolute_module_path: str, workflow_root: s
         return "." + remaining_path
 
 
+def _find_workflow_root_with_metadata(trigger_module: str) -> Optional[str]:
+    """
+    Find the workflow root module by searching for metadata.json up the module hierarchy.
+
+    Args:
+        trigger_module: The trigger's module path (e.g., "workflows.my_workflow.triggers.my_trigger")
+
+    Returns:
+        The workflow root module path if found, None otherwise
+    """
+    module_parts = trigger_module.split(".")
+
+    # Try searching up the module hierarchy for metadata.json
+    for i in range(len(module_parts), 0, -1):
+        potential_root = ".".join(module_parts[:i])
+        module_dir = potential_root.replace(".", os.path.sep)
+        metadata_path = os.path.join(module_dir, "metadata.json")
+
+        # Try to open the file using virtual_open to support both regular and virtual filesystems
+        # virtual_open checks BaseWorkflowFinder instances before falling back to regular open()
+        try:
+            file_handle = virtual_open(metadata_path)
+            if file_handle is not None:
+                file_handle.close()
+                return potential_root
+        except (FileNotFoundError, OSError):
+            pass
+
+    return None
+
+
 def _get_trigger_id_from_metadata(trigger_class: Type["BaseTrigger"]) -> Optional[UUID]:
     """
     Get the trigger ID from metadata.json for a given trigger class.
@@ -82,50 +113,56 @@ def _get_trigger_id_from_metadata(trigger_class: Type["BaseTrigger"]) -> Optiona
     return trigger_path_to_id_mapping.get(relative_trigger_path)
 
 
-def _find_workflow_root_with_metadata(trigger_module: str) -> Optional[str]:
+@lru_cache(maxsize=128)
+def _get_trigger_path_to_id_mapping(module_path: str) -> Dict[str, UUID]:
     """
-    Find the workflow root module by searching for metadata.json up the module hierarchy.
+    Read trigger path to ID mapping from metadata.json for a given module.
+
+    This function is cached to avoid repeated file reads. It searches up the module
+    hierarchy for metadata.json and extracts the trigger_path_to_id_mapping.
 
     Args:
-        trigger_module: The trigger's module path (e.g., "workflows.my_workflow.triggers.my_trigger")
+        module_path: The module path to search from (e.g., "workflows.my_workflow.triggers.my_trigger")
 
     Returns:
-        The workflow root module path if found, None otherwise
+        Dictionary mapping trigger module paths to their UUIDs
     """
-    module_parts = trigger_module.split(".")
+    try:
+        # Find the workflow root that contains metadata.json
+        workflow_root = _find_workflow_root_with_metadata(module_path)
+        if not workflow_root:
+            return {}
 
-    # Try searching up the module hierarchy for metadata.json
-    for i in range(len(module_parts), 0, -1):
-        potential_root = ".".join(module_parts[:i])
-        module_dir = potential_root.replace(".", os.path.sep)
+        # Convert module path to file path
+        module_dir = workflow_root.replace(".", os.path.sep)
         metadata_path = os.path.join(module_dir, "metadata.json")
 
-        # Try to open the file using virtual_open to support both regular and virtual filesystems
-        # virtual_open checks BaseWorkflowFinder instances before falling back to regular open()
-        try:
-            file_handle = virtual_open(metadata_path)
-            if file_handle is not None:
-                file_handle.close()
-                return potential_root
-        except (FileNotFoundError, OSError):
-            pass
+        # Use virtual_open to support both regular and virtual environments
+        with virtual_open(metadata_path) as f:
+            metadata_json = json.load(f)
+            trigger_mapping = metadata_json.get("trigger_path_to_id_mapping", {})
 
-    return None
+            # Convert string IDs to UUIDs
+            return {path: UUID(id_str) for path, id_str in trigger_mapping.items()}
+
+    except (FileNotFoundError, json.JSONDecodeError, ValueError, KeyError):
+        # If there's any error reading or parsing the file, return empty dict
+        return {}
 
 
 @lru_cache(maxsize=128)
-def _get_trigger_path_to_id_mapping(module_path: str) -> Dict[str, UUID]:
+def _get_trigger_attribute_id_mapping(module_path: str) -> Dict[str, UUID]:
     """
-    Read trigger path to ID mapping from metadata.json for a given module.
+    Read trigger attribute ID mapping from metadata.json for a given module.
 
     This function is cached to avoid repeated file reads. It searches up the module
-    hierarchy for metadata.json and extracts the trigger_path_to_id_mapping.
+    hierarchy for metadata.json and extracts the trigger_attribute_id_mapping.
 
     Args:
         module_path: The module path to search from (e.g., "workflows.my_workflow.triggers.my_trigger")
 
     Returns:
-        Dictionary mapping trigger module paths to their UUIDs
+        Dictionary mapping "<trigger_path>|<attribute_key>" to their UUIDs
     """
     try:
         # Find the workflow root that contains metadata.json
@@ -140,16 +177,55 @@ def _get_trigger_path_to_id_mapping(module_path: str) -> Dict[str, UUID]:
         # Use virtual_open to support both regular and virtual environments
         with virtual_open(metadata_path) as f:
             metadata_json = json.load(f)
-            trigger_mapping = metadata_json.get("trigger_path_to_id_mapping", {})
+            raw_mapping = metadata_json.get("trigger_attribute_id_mapping", {}) or {}
+
+        # Convert string IDs to UUIDs, skipping invalid entries
+        result: Dict[str, UUID] = {}
+        for key, id_str in raw_mapping.items():
+            try:
+                result[key] = UUID(id_str)
+            except ValueError:
+                # Skip invalid UUID entries; they will fall back to hash-based IDs
+                continue
 
-            # Convert string IDs to UUIDs
-            return {path: UUID(id_str) for path, id_str in trigger_mapping.items()}
+        return result
 
-    except (FileNotFoundError, json.JSONDecodeError, ValueError, KeyError):
+    except (FileNotFoundError, json.JSONDecodeError, KeyError):
         # If there's any error reading or parsing the file, return empty dict
         return {}
 
 
+def _get_trigger_attribute_id_from_metadata(trigger_class: Type["BaseTrigger"], attribute_name: str) -> Optional[UUID]:
+    """
+    Get the trigger attribute ID from metadata.json for a given trigger class and attribute name.
+
+    Args:
+        trigger_class: The trigger class containing the attribute
+        attribute_name: The name of the attribute
+
+    Returns:
+        The UUID from metadata.json, or None if not found
+    """
+    workflow_root = _find_workflow_root_with_metadata(trigger_class.__module__)
+    if not workflow_root:
+        return None
+
+    attribute_mapping = _get_trigger_attribute_id_mapping(trigger_class.__module__)
+    if not attribute_mapping:
+        return None
+
+    # Convert module path to relative path and append class name
+    # e.g., "root_module.triggers.scheduled" + "ScheduleTrigger" -> ".triggers.scheduled.ScheduleTrigger"
+    relative_module_path = _convert_to_relative_module_path(trigger_class.__module__, workflow_root)
+    if not relative_module_path:
+        return None
+
+    # Build the key: "<trigger_path>|<attribute_key>"
+    relative_trigger_path = f"{relative_module_path}.{trigger_class.__qualname__}"
+    key = f"{relative_trigger_path}|{attribute_name}"
+    return attribute_mapping.get(key)
+
+
 class BaseTriggerMeta(ABCMeta):
     def __new__(mcs, name: str, bases: Tuple[Type, ...], dct: Dict[str, Any]) -> Any:
         if "Display" not in dct:
@@ -388,4 +464,60 @@ class BaseTrigger(ABC, metaclass=BaseTriggerMeta):
     def bind_to_state(self, state: "BaseState") -> None:
         """Persist this trigger's attribute values onto the provided state."""
 
+        if state.meta.trigger_attributes is None:
+            state.meta.trigger_attributes = {}
         state.meta.trigger_attributes.update(self.to_trigger_attribute_values())
+
+    __trigger_name__: ClassVar[str] = "trigger"
+
+    @classmethod
+    def get_attribute_id(cls, attribute_name: str) -> UUID:
+        """
+        Get the ID for a trigger attribute, first checking metadata.json for a stable ID,
+        then falling back to a deterministic hash-based ID.
+
+        This ensures trigger attribute IDs remain stable across serialization round-trips
+        when metadata.json is present.
+
+        Args:
+            attribute_name: The name of the attribute
+
+        Returns:
+            The UUID for the attribute
+        """
+        # First try to get the ID from metadata.json
+        metadata_id = _get_trigger_attribute_id_from_metadata(cls, attribute_name)
+        if metadata_id is not None:
+            return metadata_id
+
+        # Fall back to deterministic hash-based ID
+        return get_trigger_attribute_id(cls, attribute_name)
+
+    class Config:
+        """Configuration for trigger behavior. Subclasses can override."""
+
+        pass
+
+    def __on_workflow_initiated__(self, state: "BaseState") -> None:
+        """
+        Lifecycle hook called by WorkflowRunner when workflow execution starts.
+
+        Subclasses can override to perform state initialization (e.g., appending
+        user messages to chat history so nodes can reference them).
+
+        Args:
+            state: The initial workflow state
+        """
+        pass
+
+    def __on_workflow_fulfilled__(self, state: "BaseState") -> None:
+        """
+        Lifecycle hook called by WorkflowRunner before workflow outputs are resolved.
+
+        Subclasses can override to perform state updates that should be reflected
+        in workflow outputs (e.g., appending assistant messages to chat history).
+
+        Args:
+            state: The final workflow state
+        """
+        pass

vellum/workflows/triggers/chat_message.py

@@ -0,0 +1,141 @@
+from typing import TYPE_CHECKING, Any, ClassVar, List, Optional, Union
+
+from vellum.client.types import (
+    ArrayChatMessageContent,
+    ArrayChatMessageContentItem,
+    AudioChatMessageContent,
+    ChatMessage,
+    ChatMessageContent,
+    DocumentChatMessageContent,
+    FunctionCallChatMessageContent,
+    ImageChatMessageContent,
+    StringChatMessageContent,
+    VideoChatMessageContent,
+)
+from vellum.workflows.descriptors.base import BaseDescriptor
+from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.references.lazy import LazyReference
+from vellum.workflows.references.output import OutputReference
+from vellum.workflows.triggers.base import BaseTrigger
+from vellum.workflows.utils.pydantic_schema import validate_obj_as
+
+if TYPE_CHECKING:
+    from vellum.workflows.state.base import BaseState
+
+
+class ChatMessageTrigger(BaseTrigger):
+    """
+    Trigger for chat-based workflows that supports multi-turn conversations.
+
+    Appends user message to state.chat_history at workflow start, and assistant
+    response after workflow completion. Use previous_execution_id to maintain
+    conversation state across executions.
+
+    Attributes:
+        message: The incoming chat message content. Can be a string or a list of content items.
+    """
+
+    message: Union[str, List[ArrayChatMessageContentItem]]
+
+    class Config(BaseTrigger.Config):
+        output: Optional[BaseDescriptor[Any]] = None
+
+    def __init__(self, **kwargs: Any):
+        """Initialize ChatMessageTrigger, converting VellumValue objects to ChatMessageContent if needed."""
+        # Convert message from VellumValue format to ChatMessageContent format if needed
+        if "message" in kwargs:
+            message = kwargs["message"]
+            # Handle string messages by converting to a list with a single StringChatMessageContent
+            if isinstance(message, str):
+                kwargs["message"] = [StringChatMessageContent(value=message)]
+            elif isinstance(message, list):
+                converted_message = []
+                for item in message:
+                    # If it's already a ChatMessageContent type, keep it as-is
+                    if isinstance(
+                        item,
+                        (
+                            StringChatMessageContent,
+                            ImageChatMessageContent,
+                            AudioChatMessageContent,
+                            VideoChatMessageContent,
+                            DocumentChatMessageContent,
+                            FunctionCallChatMessageContent,
+                        ),
+                    ):
+                        converted_message.append(item)
+                    # Handle raw strings in the array by wrapping them in StringChatMessageContent
+                    elif isinstance(item, str):
+                        converted_message.append(StringChatMessageContent(value=item))
+                    # Convert VellumValue objects or dicts to ChatMessageContent
+                    # Use discriminated union validation
+                    else:
+                        # Get the dict representation (either from Pydantic model or already a dict)
+                        item_dict = item.model_dump() if hasattr(item, "model_dump") else item
+                        converted_message.append(
+                            validate_obj_as(ArrayChatMessageContentItem, item_dict)  # type: ignore[arg-type]
+                        )
+
+                kwargs["message"] = converted_message
+
+        super().__init__(**kwargs)
+
+    def __on_workflow_initiated__(self, state: "BaseState") -> None:
+        """Appends user message to state.chat_history at workflow start."""
+        if not hasattr(state, "chat_history"):
+            return
+
+        if state.chat_history is None:
+            state.chat_history = []
+
+        if isinstance(self.message, str):
+            user_message = ChatMessage(
+                role="USER",
+                text=self.message,
+            )
+        else:
+            user_message = ChatMessage(
+                role="USER",
+                content=ArrayChatMessageContent(value=self.message),
+            )
+        state.chat_history.append(user_message)
+
+    def __on_workflow_fulfilled__(self, state: "BaseState") -> None:
+        """Appends assistant response to state.chat_history after workflow completion."""
+        if not hasattr(state, "chat_history"):
+            return
+
+        if state.chat_history is None:
+            state.chat_history = []
+
+        output = self.Config.output
+        if output is not None:
+            resolved_output = self._resolve_output(output, state)
+            assistant_message = ChatMessage(
+                role="ASSISTANT",
+                content=resolved_output if not isinstance(resolved_output, str) else None,
+                text=resolved_output if isinstance(resolved_output, str) else None,
+            )
+            state.chat_history.append(assistant_message)
+
+    def _resolve_output(
+        self,
+        output: BaseDescriptor[Any],
+        state: "BaseState",
+    ) -> Union[str, ChatMessageContent]:
+        """Resolves output reference, handling workflow output references."""
+        descriptor = output
+        if isinstance(output, LazyReference) and callable(output._get):
+            descriptor = output._get()
+
+        if isinstance(descriptor, OutputReference) and isinstance(descriptor.instance, BaseDescriptor):
+            return resolve_value(descriptor.instance, state)
+
+        return resolve_value(output, state)
+
+    __trigger_name__: ClassVar[str] = "chat"
+
+    class Display(BaseTrigger.Display):
+        label: str = "Chat Message"
+        icon: Optional[str] = "vellum:icon:message-dots"
+        color: Optional[str] = "blue"

vellum/workflows/triggers/integration.py

@@ -13,6 +13,8 @@ class IntegrationTriggerMeta(BaseTriggerMeta):
     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":
@@ -36,6 +38,16 @@ class IntegrationTriggerMeta(BaseTriggerMeta):
                 # 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
 
 

vellum/workflows/triggers/manual.py

@@ -1,3 +1,5 @@
+from typing import ClassVar
+
 from vellum.workflows.triggers.base import BaseTrigger
 
 
@@ -34,4 +36,4 @@ class ManualTrigger(BaseTrigger):
         - ManualTrigger: Executes when explicitly called
     """
 
-    pass
+    __trigger_name__: ClassVar[str] = "manual"

vellum/workflows/triggers/schedule.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import Optional
+from typing import ClassVar, Optional
 
 from vellum.workflows.triggers.base import BaseTrigger
 
@@ -16,3 +16,5 @@ class ScheduleTrigger(BaseTrigger):
     class Config:
         cron: str
         timezone: Optional[str] = None
+
+    __trigger_name__: ClassVar[str] = "scheduled"