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

vellum/workflows/utils/uuids.py

@@ -1,8 +1,13 @@
 import hashlib
+import sys
 from uuid import UUID
 from typing import TYPE_CHECKING
 
+from vellum.workflows.loaders.base import BaseWorkflowFinder
+
 if TYPE_CHECKING:
+    from vellum.workflows.inputs.base import BaseInputs
+    from vellum.workflows.state.base import BaseState
     from vellum.workflows.triggers.base import BaseTrigger
 
 
@@ -21,6 +26,59 @@ def generate_workflow_deployment_prefix(deployment_name: str, release_tag: str)
     return f"vellum_workflow_deployment_{expected_hash}"
 
 
+def _normalize_module_path(module_path: str) -> str:
+    """
+    Normalize a module path by filtering out a leading ephemeral namespace segment.
+
+    When workflows are loaded dynamically (e.g., via VirtualFileFinder), the module path
+    may start with an ephemeral namespace that changes on each invocation. This function
+    strips that leading segment to ensure stable, deterministic ID generation.
+
+    The function checks if the first segment of the module path exactly matches the
+    namespace of any registered BaseWorkflowFinder in sys.meta_path. Only namespaces
+    that are actually registered are stripped, preventing accidental stripping of
+    legitimate module names.
+
+    Args:
+        module_path: The module path to normalize (e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890.workflow"
+                     or "workflow_tmp_ABC123xyz.workflow")
+
+    Returns:
+        The normalized module path with the leading ephemeral segment removed if present
+        (e.g., "workflow")
+    """
+    parts = module_path.split(".")
+    if not parts:
+        return module_path
+
+    first_part = parts[0]
+
+    # Check if the first part matches the namespace of any registered workflow finder
+    for finder in sys.meta_path:
+        if isinstance(finder, BaseWorkflowFinder) and finder.namespace == first_part:
+            return ".".join(parts[1:]) if len(parts) > 1 else ""
+
+    return module_path
+
+
+def generate_entity_id_from_path(path: str) -> UUID:
+    """
+    Generate a deterministic entity ID from a path string.
+
+    This function normalizes the path by filtering out any leading UUID namespace segment
+    (which may change on each invocation when workflows are loaded dynamically), then
+    generates a stable UUID from the normalized path.
+
+    Args:
+        path: The path string to generate an ID from (e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890.workflow.MyNode")
+
+    Returns:
+        A deterministic UUID based on the normalized path
+    """
+    normalized_path = _normalize_module_path(path)
+    return uuid4_from_hash(normalized_path)
+
+
 def uuid4_from_hash(input_str: str) -> UUID:
     # Create a SHA-256 hash of the input string
     hash_bytes = hashlib.sha256(input_str.encode()).digest()
@@ -57,3 +115,35 @@ def get_trigger_attribute_id(trigger_class: "type[BaseTrigger]", attribute_name:
     """
     trigger_id = trigger_class.__id__
     return uuid4_from_hash(f"{trigger_id}|{attribute_name}")
+
+
+def get_workflow_input_id(inputs_class: "type[BaseInputs]", input_name: str) -> UUID:
+    """
+    Generate a deterministic workflow input ID from an inputs class and input name
+    using the class's parent workflow ID and input name to ensure stability and uniqueness.
+
+    Args:
+        inputs_class: The inputs class containing the input
+        input_name: The name of the input
+
+    Returns:
+        A deterministic UUID based on the workflow ID and input name
+    """
+    workflow_class = inputs_class.__parent_class__
+    workflow_id = workflow_class.__id__
+    return uuid4_from_hash(f"{workflow_id}|inputs|id|{input_name}")
+
+
+def get_state_value_id(state_class: "type[BaseState]", state_value_name: str) -> UUID:
+    """
+    Generate a deterministic state value ID from a state class and state value name
+    using the class's module name, qualname, and state value name to ensure stability and uniqueness.
+
+    Args:
+        state_class: The state class containing the state value
+        state_value_name: The name of the state value
+
+    Returns:
+        A deterministic UUID based on the state class module, qualname, and state value name
+    """
+    return uuid4_from_hash(f"{state_class.__module__}.{state_class.__qualname__}|state_values|id|{state_value_name}")

vellum/workflows/utils/validate.py

@@ -0,0 +1,108 @@
+from typing import Any, Union, get_args, get_origin
+
+
+class TypeValidationError(ValueError):
+    """Exception raised when type validation fails."""
+
+    def __init__(self, declared_type: type, target_type: type) -> None:
+        declared_type_name = getattr(declared_type, "__name__", str(declared_type))
+        target_type_name = getattr(target_type, "__name__", str(target_type))
+        super().__init__(
+            f"Output type mismatch: declared type '{declared_type_name}' "
+            f"but the 'value' Output has type(s) '{target_type_name}'. "
+        )
+        self.declared_type = declared_type
+        self.target_type = target_type
+
+
+def validate_target_type(declared_type: type, target_type: type) -> None:
+    # If either type is Any, validation always passes
+    if declared_type is Any or target_type is Any:
+        return
+
+    declared_origin = get_origin(declared_type)
+    target_origin = get_origin(target_type)
+
+    # Special case: both are Unions
+    # Each target union member must be compatible with at least one declared union member
+    if declared_origin is Union and target_origin is Union:
+        declared_union_args = get_args(declared_type)
+        target_union_args = get_args(target_type)
+        for target_member in target_union_args:
+            is_compatible = False
+            for declared_member in declared_union_args:
+                try:
+                    validate_target_type(declared_member, target_member)
+                    is_compatible = True
+                    break
+                except TypeValidationError:
+                    continue
+            if not is_compatible:
+                # This target member is not compatible with any declared member
+                raise TypeValidationError(declared_type, target_type)
+        # All target members are compatible with at least one declared member
+        return
+
+    # If declared_type is a Union, target_type must be compatible with at least one union member
+    if declared_origin is Union:
+        declared_union_args = get_args(declared_type)
+        for union_member in declared_union_args:
+            try:
+                validate_target_type(union_member, target_type)
+                # If any union member is compatible, validation passes
+                return
+            except TypeValidationError:
+                # This union member is incompatible, try the next one
+                continue
+        # None of the union members are compatible with target_type
+        raise TypeValidationError(declared_type, target_type)
+
+    # If target_type is a Union, ALL union members must be compatible with declared_type
+    if target_origin is Union:
+        target_union_args = get_args(target_type)
+        for union_member in target_union_args:
+            try:
+                validate_target_type(declared_type, union_member)
+            except TypeValidationError:
+                # At least one union member is incompatible with declared_type
+                raise TypeValidationError(declared_type, target_type)
+        # All union members are compatible with declared_type
+        return
+
+    # Check for exact type match
+    if target_type == declared_type:
+        return
+
+    # Check for subclass relationships
+    try:
+        if issubclass(target_type, declared_type) or issubclass(declared_type, target_type):
+            return
+    except TypeError:
+        # Handle cases where types aren't classes (e.g., generic types)
+        if str(target_type) == str(declared_type):
+            return
+
+    # Check for generic type compatibility
+    declared_origin = get_origin(declared_type)
+
+    if target_origin is None and declared_origin is None:
+        # Neither is a generic type, and they don't match
+        raise TypeValidationError(declared_type, target_type)
+
+    if target_origin == declared_type or declared_origin == target_type or target_origin == declared_origin:
+        target_args = get_args(target_type)
+        declared_args = get_args(declared_type)
+
+        if len(declared_args) == 0:
+            return
+
+        if len(target_args) != len(declared_args):
+            raise TypeValidationError(declared_type, target_type)
+
+        for target_arg, declared_arg in zip(target_args, declared_args):
+            validate_target_type(declared_arg, target_arg)
+
+        return
+
+    # If we reach here, types don't match
+    raise TypeValidationError(declared_type, target_type)

vellum/workflows/utils/vellum_variables.py

@@ -1,7 +1,10 @@
+from datetime import datetime
+import sys
 import typing
 from typing import Any, List, Tuple, Type, Union, get_args, get_origin
 
 from vellum import (
+    ArrayChatMessageContentItem,
     ChatMessage,
     ChatMessageRequest,
     FunctionCall,
@@ -24,7 +27,7 @@ from vellum import (
 )
 from vellum.workflows.constants import undefined
 from vellum.workflows.descriptors.base import BaseDescriptor
-from vellum.workflows.types.core import Json
+from vellum.workflows.types.core import is_json_type
 
 
 def primitive_type_to_vellum_variable_type(type_: Union[Type, BaseDescriptor]) -> VellumVariableType:
@@ -46,17 +49,7 @@ def primitive_type_to_vellum_variable_type(type_: Union[Type, BaseDescriptor]) -
             return "JSON"
 
         if len(types) != 1:
-            # Check explicitly for our internal JSON type.
-            # Matches the type found at vellum.workflows.utils.vellum_variables.Json
-            actual_types_with_explicit_ref = [
-                bool,
-                int,
-                float,
-                str,
-                typing.List[Json],
-                typing.Dict[str, Json],
-            ]
-            if types == actual_types_with_explicit_ref:
+            if is_json_type(types):
                 return "JSON"
             # Number now supports float and int
             elif types == [float, int]:
@@ -66,11 +59,15 @@ def primitive_type_to_vellum_variable_type(type_: Union[Type, BaseDescriptor]) -
             if len(collapse_types) == 1:
                 return primitive_type_to_vellum_variable_type(collapse_types[0])
 
+            # Handle Union[str, List[ArrayChatMessageContentItem]] for ChatMessageTrigger.message
+            if _is_string_and_array_chat_message_content_union(types):
+                return "ARRAY"
+
             raise ValueError(f"Expected Descriptor to only have one type, got {types}")
 
         type_ = type_.types[0]
 
-    if _is_type_optionally_equal(type_, str):
+    if _is_type_optionally_in(type_, (str, datetime)):
         return "STRING"
     elif _is_type_optionally_in(type_, (int, float)):
         return "NUMBER"
@@ -218,8 +215,91 @@ def _builtin_list_to_vellum_type(type_: Type) -> Union[str, None]:
                 item_type, SearchResultRequest
             ):
                 return "SEARCH_RESULTS"
-            if _is_type_optionally_equal(item_type, VellumValue) or _is_type_optionally_equal(
-                item_type, VellumValueRequest
-            ):
+
+            if _is_vellum_value_subtype(item_type):
                 return "ARRAY"
+
+            if _is_array_chat_message_content_item(item_type):
+                return "ARRAY"
+
     return None
+
+
+def _is_array_chat_message_content_item(type_: Type) -> bool:
+    """Check if the type is ArrayChatMessageContentItem or a union of its subtypes."""
+    array_content_item_types = list(typing.get_args(ArrayChatMessageContentItem))
+
+    origin = get_origin(type_)
+    if not origin:
+        if isinstance(type_, type):
+            return any(issubclass(type_, t) for t in array_content_item_types if isinstance(t, type))
+        return False
+
+    if origin is typing.Union:
+        args = get_args(type_)
+        return all(_is_array_chat_message_content_item(arg) for arg in args)
+
+    return type_ == ArrayChatMessageContentItem
+
+
+def _is_string_and_array_chat_message_content_union(types: List[Type]) -> bool:
+    """Check if types represent Union[str, List[ArrayChatMessageContentItem]]."""
+    if len(types) != 2:
+        return False
+
+    has_str = str in types
+    has_list_array_content = any(
+        get_origin(t) in (list, typing.List)
+        and len(get_args(t)) == 1
+        and _is_array_chat_message_content_item(get_args(t)[0])
+        for t in types
+    )
+
+    return has_str and has_list_array_content
+
+
+def _is_vellum_value_subtype(type_: Type) -> bool:
+    # This logic is here primarily for `ArrayVellumValue`, which is defined recursively.
+    # At class definition time, we invoke some Pydantic helpers to resolve its forward references.
+    vellum_value_types = [
+        (
+            t.__forward_value__
+            if isinstance(t, typing.ForwardRef) and t.__forward_evaluated__ and t.__forward_value__ is not None
+            else t
+        )
+        for t in typing.get_args(VellumValue)
+    ]
+    origin = get_origin(type_)
+    if not origin:
+        if isinstance(type_, type):
+            return any(issubclass(type_, vellum_value_type) for vellum_value_type in vellum_value_types)
+        elif isinstance(type_, typing.ForwardRef):
+            # If the forward ref hasn't been resolved yet, do the simple stupid thing and
+            # assume it's not a VellumValue subtype.
+            # This means user-defined types should use the fully resolved types!
+            if not type_.__forward_evaluated__ or type_.__forward_value__ is None:
+                return False
+
+            type_ = type_.__forward_value__
+            if isinstance(type_, type):
+                return any(issubclass(type_, vellum_value_type) for vellum_value_type in vellum_value_types)
+            else:
+                return False
+        else:
+            return False
+
+    if sys.version_info >= (3, 10) and sys.version_info < (3, 14):
+        # See https://docs.python.org/3/library/types.html#types.UnionType.
+        # In Python 3.10, `types.UnionType` was introduced to support X | Y union type expressions.
+        # In Python 3.14, `types.UnionType` is just an alias for `typing.Union`.
+        from types import UnionType
+
+        union_types = (typing.Union, UnionType)
+    else:
+        union_types = (typing.Union,)
+
+    if origin in union_types:
+        args = get_args(type_)
+        return all(_is_vellum_value_subtype(arg) for arg in args)
+
+    return False