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

vellum/workflows/triggers/tests/test_chat_message.py

@@ -0,0 +1,257 @@
+"""Tests for ChatMessageTrigger."""
+
+import pytest
+from typing import List, Optional
+
+from pydantic import Field
+
+from vellum.client.types import (
+    ArrayChatMessageContent,
+    ArrayChatMessageContentItem,
+    ChatMessage,
+    ImageChatMessageContent,
+    StringChatMessageContent,
+    StringVellumValue,
+    VellumImage,
+)
+from vellum.workflows.inputs.base import BaseInputs
+from vellum.workflows.nodes.bases.base import BaseNode
+from vellum.workflows.outputs import BaseOutputs
+from vellum.workflows.state.base import BaseState
+from vellum.workflows.triggers.chat_message import ChatMessageTrigger
+from vellum.workflows.workflows.base import BaseWorkflow
+
+
+class ChatState(BaseState):
+    chat_history: List[ChatMessage] = Field(default_factory=list)
+
+
+@pytest.mark.parametrize(
+    ["message", "expected_content"],
+    [
+        pytest.param(
+            [StringChatMessageContent(value="Hello, world!")],
+            ArrayChatMessageContent(value=[StringChatMessageContent(value="Hello, world!")]),
+            id="text_string_content",
+        ),
+        pytest.param(
+            [ImageChatMessageContent(value=VellumImage(src="https://example.com/image.jpg"))],
+            ArrayChatMessageContent(
+                value=[ImageChatMessageContent(value=VellumImage(src="https://example.com/image.jpg"))]
+            ),
+            id="multimodal_image",
+        ),
+        pytest.param(
+            [
+                StringChatMessageContent(value="Look at this image:"),
+                ImageChatMessageContent(value=VellumImage(src="https://example.com/image.jpg")),
+            ],
+            ArrayChatMessageContent(
+                value=[
+                    StringChatMessageContent(value="Look at this image:"),
+                    ImageChatMessageContent(value=VellumImage(src="https://example.com/image.jpg")),
+                ]
+            ),
+            id="text_and_multimodal_array",
+        ),
+    ],
+)
+def test_chat_message_trigger__initiated(
+    message: List[ArrayChatMessageContentItem],
+    expected_content: ArrayChatMessageContent,
+):
+    """Tests that ChatMessageTrigger appends user message on workflow initiation."""
+
+    # GIVEN a ChatMessageTrigger with a message
+    trigger = ChatMessageTrigger(message=message)
+
+    # AND a state with chat_history
+    state = ChatState()
+
+    # WHEN the initiated lifecycle hook is called
+    trigger.__on_workflow_initiated__(state)
+
+    # THEN the user message is appended to chat_history
+    assert len(state.chat_history) == 1
+    assert state.chat_history[0].role == "USER"
+    assert state.chat_history[0].text is None
+    assert state.chat_history[0].content == expected_content
+
+
+def test_chat_message_trigger__state_without_chat_history():
+    """Tests that ChatMessageTrigger handles state without chat_history gracefully."""
+
+    # GIVEN a ChatMessageTrigger with a message
+    trigger = ChatMessageTrigger(message=[StringChatMessageContent(value="Hello")])
+
+    # AND a state without chat_history attribute
+    state = BaseState()
+
+    # WHEN the initiated lifecycle hook is called
+    trigger.__on_workflow_initiated__(state)
+
+    # THEN no error is raised and state is unchanged
+    assert not hasattr(state, "chat_history")
+
+
+def test_chat_message_trigger__graph_syntax():
+    """Tests that ChatMessageTrigger can be used in graph syntax."""
+
+    # GIVEN a ChatMessageTrigger and a node
+    class TestNode(BaseNode):
+        pass
+
+    # WHEN we use trigger >> node syntax
+    graph = ChatMessageTrigger >> TestNode
+
+    # THEN a graph is created with the trigger edge
+    assert graph is not None
+    assert len(list(graph.trigger_edges)) == 1
+    assert list(graph.trigger_edges)[0].trigger_class == ChatMessageTrigger
+    assert list(graph.trigger_edges)[0].to_node == TestNode
+
+
+def test_chat_message_trigger__converts_vellum_value_objects():
+    """Tests that ChatMessageTrigger converts VellumValue objects to ChatMessageContent."""
+
+    # GIVEN a message as VellumValue objects (as received from codegen/API)
+    vellum_value_message = [
+        StringVellumValue(type="STRING", value="Hello, world!"),
+    ]
+
+    # WHEN a ChatMessageTrigger is created with VellumValue objects
+    trigger = ChatMessageTrigger(message=vellum_value_message)
+
+    # THEN the message is converted to ChatMessageContent
+    assert len(trigger.message) == 1
+    assert isinstance(trigger.message[0], StringChatMessageContent)
+    assert trigger.message[0].value == "Hello, world!"
+
+    # AND the trigger works correctly with state
+    state = ChatState()
+    trigger.__on_workflow_initiated__(state)
+
+    assert len(state.chat_history) == 1
+    assert state.chat_history[0].role == "USER"
+    assert state.chat_history[0].content == ArrayChatMessageContent(
+        value=[StringChatMessageContent(value="Hello, world!")]
+    )
+
+
+def test_chat_message_trigger__converts_dict_format():
+    """Tests that ChatMessageTrigger converts dict format to ChatMessageContent."""
+
+    # GIVEN a message as dict objects (alternative API format)
+    dict_message = [
+        {"type": "STRING", "value": "Hello from dict!"},
+    ]
+
+    # WHEN a ChatMessageTrigger is created with dict objects
+    trigger = ChatMessageTrigger(message=dict_message)
+
+    # THEN the message is converted to ChatMessageContent
+    assert len(trigger.message) == 1
+    assert isinstance(trigger.message[0], StringChatMessageContent)
+    assert trigger.message[0].value == "Hello from dict!"
+
+
+def test_chat_message_trigger__converts_string_message():
+    """Tests that ChatMessageTrigger converts string messages to ChatMessageContent list."""
+
+    # GIVEN a message as a string
+    string_message = "Hello, world!"
+
+    # WHEN a ChatMessageTrigger is created with a string message
+    trigger = ChatMessageTrigger(message=string_message)
+
+    # THEN the message is converted to a list with a single StringChatMessageContent
+    assert len(trigger.message) == 1
+    assert isinstance(trigger.message[0], StringChatMessageContent)
+    assert trigger.message[0].value == "Hello, world!"
+
+    # AND the trigger works correctly with state
+    state = ChatState()
+    trigger.__on_workflow_initiated__(state)
+
+    assert len(state.chat_history) == 1
+    assert state.chat_history[0].role == "USER"
+    assert state.chat_history[0].content == ArrayChatMessageContent(
+        value=[StringChatMessageContent(value="Hello, world!")]
+    )
+
+
+def test_chat_message_trigger__raw_string_array__workflow_stream():
+    """Tests that workflow.stream() works with raw string array after deserialize_trigger."""
+
+    # GIVEN a workflow with ChatMessageTrigger
+    class TestNode(BaseNode):
+        class Outputs(BaseOutputs):
+            result: str
+
+        def run(self) -> Outputs:
+            return self.Outputs(result="success")
+
+    class TestWorkflow(BaseWorkflow):
+        graph = ChatMessageTrigger >> TestNode
+
+    # AND a raw string array input (not wrapped in VellumValue format)
+    raw_string_array_input = {"message": ["Hello", "World"]}
+
+    # WHEN we deserialize the trigger with raw string array
+    trigger = TestWorkflow.deserialize_trigger(
+        trigger_id=ChatMessageTrigger.__id__,
+        inputs=raw_string_array_input,
+    )
+
+    # THEN the trigger is properly deserialized
+    assert isinstance(trigger, ChatMessageTrigger)
+    assert len(trigger.message) == 2
+    assert isinstance(trigger.message[0], StringChatMessageContent)
+    assert trigger.message[0].value == "Hello"
+    assert isinstance(trigger.message[1], StringChatMessageContent)
+    assert trigger.message[1].value == "World"
+
+    # AND the workflow can be streamed successfully
+    workflow = TestWorkflow()
+    events = list(workflow.stream(trigger=trigger))
+
+    # THEN the workflow completes successfully
+    assert len(events) > 0
+
+
+def test_chat_message_trigger__chat_history_defaulted_to_none():
+    """Tests that workflow runs successfully when chat_history is defaulted to None."""
+
+    # GIVEN a state with chat_history defaulted to None
+    class NullableChatHistoryState(BaseState):
+        chat_history: Optional[List[ChatMessage]] = None
+
+    # AND a simple node
+    class TestNode(BaseNode):
+        class Outputs(BaseOutputs):
+            result: str
+
+        def run(self) -> Outputs:
+            return self.Outputs(result="success")
+
+    # AND a workflow with ChatMessageTrigger and the nullable chat_history state
+    class TestWorkflow(BaseWorkflow[BaseInputs, NullableChatHistoryState]):
+        graph = ChatMessageTrigger >> TestNode
+
+    # WHEN we run the workflow with a trigger
+    trigger = ChatMessageTrigger(message="Hello")
+    workflow = TestWorkflow()
+    terminal_event = workflow.run(trigger=trigger)
+
+    # THEN the workflow completes successfully
+    assert terminal_event.name == "workflow.execution.fulfilled"
+
+    # AND the final state has a contentful chat_history
+    final_state = terminal_event.final_state
+    assert final_state is not None
+    assert final_state.chat_history is not None
+    assert len(final_state.chat_history) == 1
+    assert final_state.chat_history[0].role == "USER"
+    assert final_state.chat_history[0].content == ArrayChatMessageContent(
+        value=[StringChatMessageContent(value="Hello")]
+    )

vellum/workflows/types/core.py

@@ -4,6 +4,7 @@ from threading import Event as ThreadingEvent
 from typing import (  # type: ignore[attr-defined]
     Any,
     Dict,
+    Iterable,
     List,
     Union,
     _GenericAlias,
@@ -17,6 +18,23 @@ JsonArray = List["Json"]
 JsonObject = Dict[str, "Json"]
 Json = Union[None, bool, int, float, str, JsonArray, JsonObject]
 
+
+def is_json_type(types: Iterable) -> bool:
+    # Check explicitly for our internal JSON type.
+    # Matches the type found at vellum.workflows.types.core.Json
+    actual_types_with_explicit_ref = [
+        bool,
+        int,
+        float,
+        str,
+        List[Json],
+        Dict[str, Json],
+    ]
+    with_none = [type(None), *actual_types_with_explicit_ref]
+    types_list = list(types)
+    return types_list == actual_types_with_explicit_ref or types_list == with_none
+
+
 CancelSignal = Union[ThreadingEvent, MultiprocessingEvent]
 
 # Unions and Generics inherit from `_GenericAlias` instead of `type`

vellum/workflows/types/definition.py

@@ -181,8 +181,11 @@ class VellumIntegrationToolDefinition(UniversalBaseModel):
     integration_name: str  # "GITHUB", "SLACK", etc.
     name: str  # Specific action like "GITHUB_CREATE_AN_ISSUE"
 
-    # Required for tool base consistency
-    description: str
+    # Optional description for tool base consistency
+    description: str = ""
+
+    # Optional toolkit version for pinning
+    toolkit_version: Optional[str] = None
 
 
 class VellumIntegrationToolDetails(VellumIntegrationToolDefinition):
@@ -208,16 +211,6 @@ class MCPServer(UniversalBaseModel):
 
     model_config = {"arbitrary_types_allowed": True}
 
-    def __setattr__(self, name: str, value: Any) -> None:
-        """Override to automatically set serialization flags for environment variables."""
-        super().__setattr__(name, value)
-
-        if name == "bearer_token_value" and isinstance(value, EnvironmentVariableReference):
-            value.serialize_as_constant = True
-
-        if name == "api_key_header_value" and isinstance(value, EnvironmentVariableReference):
-            value.serialize_as_constant = True
-
 
 class MCPToolDefinition(UniversalBaseModel):
     name: str
@@ -234,4 +227,4 @@ ToolBase = Union[
     ComposioToolDefinition,
     VellumIntegrationToolDefinition,
 ]
-Tool = Union[ToolBase, MCPServer]
+Tool = Union[ToolBase, MCPServer, MCPToolDefinition]

vellum/workflows/types/generics.py

@@ -6,6 +6,7 @@ if TYPE_CHECKING:
     from vellum.workflows import BaseWorkflow
     from vellum.workflows.inputs import BaseInputs
     from vellum.workflows.nodes import BaseNode
+    from vellum.workflows.nodes.bases.base_adornment_node import BaseAdornmentNode
     from vellum.workflows.outputs import BaseOutputs
     from vellum.workflows.state import BaseState
 
@@ -37,6 +38,17 @@ def import_workflow_class() -> Type["BaseWorkflow"]:
     return BaseWorkflow
 
 
+@cache
+def import_base_adornment_node() -> Type["BaseAdornmentNode"]:
+    """
+    Helper function to help avoid circular imports.
+    """
+
+    from vellum.workflows.nodes.bases.base_adornment_node import BaseAdornmentNode
+
+    return BaseAdornmentNode
+
+
 def is_node_class(obj: Any) -> TypeGuard[Type["BaseNode"]]:
     base_node_class = _import_node_class()
     return isinstance(obj, type) and issubclass(obj, base_node_class)

vellum/workflows/types/tests/test_utils.py

@@ -101,3 +101,15 @@ def test_infer_types(cls, attr_name, expected_type):
 )
 def test_class_attr_names(cls, expected_attr_names):
     assert get_class_attr_names(cls) == expected_attr_names
+
+
+def test_infer_types__non_existent_attribute__raises_clear_error():
+    """Test that infer_types raises a clear error message for non-existent attributes."""
+
+    # GIVEN a class with some attributes
+    # WHEN we try to infer types for a non-existent attribute
+    # THEN it should raise an AttributeError with a clear message
+    with pytest.raises(AttributeError) as exc_info:
+        infer_types(ExampleClass, "non_existent_attribute")
+
+    assert "'ExampleClass' has no attribute 'non_existent_attribute'" in str(exc_info.value)

vellum/workflows/types/utils.py

@@ -91,7 +91,10 @@ def infer_types(object_: Type, attr_name: str, localns: Optional[Dict[str, Any]]
                 if len(types_list) == len(parts):
                     return tuple(types_list)
 
-        type_hints = get_type_hints(class_, localns=LOCAL_NS if localns is None else {**LOCAL_NS, **localns})
+        try:
+            type_hints = get_type_hints(class_, localns=LOCAL_NS if localns is None else {**LOCAL_NS, **localns})
+        except AttributeError:
+            type_hints = {}
         if attr_name in type_hints:
             type_hint = type_hints[attr_name]
             if get_origin(type_hint) is ClassVar:
@@ -121,12 +124,14 @@ def infer_types(object_: Type, attr_name: str, localns: Optional[Dict[str, Any]]
                 class_attribute = class_attributes[attr_name]
                 return resolve_types(class_attribute)
 
-        raise AttributeError(f"Failed to infer type from attribute {attr_name} on {object_.__name__}")
+        raise AttributeError(f"'{object_.__name__}' has no attribute '{attr_name}'")
     except TypeError:
         # Python 3.13+: object class doesn't have __annotations__ by default
         # Use getattr with default to safely access annotations
         annotations = getattr(object_, "__annotations__", {})
         annotation_value = annotations.get(attr_name, undefined)
+        if annotation_value is undefined:
+            raise AttributeError(f"'{object_.__name__}' has no attribute '{attr_name}'")
         raise AttributeError(
             f"Found 3.9+ typing syntax for field '{attr_name}' on class '{object_.__name__}' – {annotation_value}. Type annotations must be compatible with python version 3.8. "  # noqa: E501
         )
@@ -219,3 +224,28 @@ def get_original_base(cls: Type) -> Type:
     # in Python 3.12, there is `from types import get_original_bases`, making this future proof
     # https://docs.python.org/3/library/types.html#types.get_original_bases
     return cls.__orig_bases__[0]  # type: ignore[attr-defined]
+
+
+def coerce_to_declared_type(value: Any, declared_type: Type, field_name: str) -> Any:
+    """Coerce a value to the declared type if needed.
+
+    This handles cases where the API returns a float for an int field
+    (since NumberVellumValue.value is typed as float).
+
+    Args:
+        value: The value to coerce
+        declared_type: The expected type from the field annotation
+        field_name: The name of the field (for error messages)
+
+    Returns:
+        The coerced value
+
+    Raises:
+        ValueError: If the value cannot be safely coerced to the declared type
+    """
+    if declared_type is int and isinstance(value, float):
+        if value.is_integer():
+            return int(value)
+        raise ValueError(f"Expected integer for input '{field_name}', but received non-integer float: {value}")
+
+    return value

vellum/workflows/types/workflow_metadata.py

@@ -0,0 +1,124 @@
+"""Pydantic models for workflow metadata.json files.
+
+The metadata.json file is generated alongside workflow code to ensure stable,
+UI-aligned identifiers without relying on Python display classes. It contains
+mappings between code paths and UI identifiers for nodes, triggers, edges, and
+dataset rows.
+"""
+
+from typing import Dict, Optional
+
+from vellum.client.core.pydantic_utilities import UniversalBaseModel
+from vellum.client.types.code_resource_definition import CodeResourceDefinition
+
+
+class RunnerConfig(UniversalBaseModel):
+    """Configuration for the workflow runner environment.
+
+    This specifies the container image and version information used to execute
+    the workflow.
+    """
+
+    container_image_name: Optional[str] = None
+    """The name of the container image to use. If not provided, defaults to the
+    standard Python workflow runtime image."""
+
+    container_image_tag: Optional[str] = None
+    """The tag of the container image to use. If not provided, defaults to the
+    latest tag."""
+
+    codegen_version: Optional[str] = None
+    """The version of codegen used to generate the workflow artifact.
+
+    .. deprecated::
+        This field is deprecated. Use `sdk_version` instead.
+    """
+
+    sdk_version: Optional[str] = None
+    """The SDK version the workflow is intended to run on."""
+
+    is_deployment_inlining_enabled: bool = False
+    """Whether deployment inlining is enabled for this workflow."""
+
+    server_version: Optional[str] = None
+    """The server version the workflow is intended to run on. This gets set when
+    deploying a workflow with a hotswappable custom image."""
+
+
+class WorkflowMetadata(UniversalBaseModel):
+    """Metadata persisted alongside generated workflow code.
+
+    This metadata ensures stable, UI-aligned identifiers without relying on
+    Python display classes. It is generated by the codegen system and consumed
+    during workflow serialization to maintain consistent IDs across round-trips.
+    """
+
+    runner_config: Optional[RunnerConfig] = None
+    """Configuration for the workflow runner environment."""
+
+    label: Optional[str] = None
+    """Human-readable label for the workflow."""
+
+    codegen_version: Optional[str] = None
+    """The version of codegen used to generate this workflow.
+
+    .. deprecated::
+        This field is deprecated. Use `runner_config.codegen_version` instead.
+    """
+
+    server_version: Optional[str] = None
+    """The server version this workflow was generated for.
+
+    .. deprecated::
+        This field is deprecated. Use `runner_config.server_version` instead.
+    """
+
+    node_id_to_file_mapping: Dict[str, CodeResourceDefinition] = {}
+    """Mapping of node IDs to their code resource definitions.
+
+    Key: Node UUID string
+    Value: CodeResourceDefinition containing the module path and class name
+    """
+
+    trigger_path_to_id_mapping: Dict[str, str] = {}
+    """Mapping of trigger class paths to their UI trigger IDs.
+
+    Key: ".<relative_trigger_module_path>.<TriggerClassName>"
+    Value: UI trigger ID (UUID string)
+    """
+
+    trigger_attribute_id_mapping: Dict[str, str] = {}
+    """Mapping of trigger attribute keys to their UI attribute IDs.
+
+    Key: "<trigger_path>|<attribute_key>"
+    Value: Attribute ID (UUID string)
+
+    This ensures trigger attribute IDs remain stable across serialization
+    round-trips.
+    """
+
+    entrypoint: Optional[str] = None
+    """The UI entrypoint node ID.
+
+    Kept for compatibility. Edge IDs for entrypoint flows are now included in
+    edges_to_id_mapping using the manual trigger path as the source.
+    """
+
+    edges_to_id_mapping: Dict[str, str] = {}
+    """Mapping of edge path keys to their UI edge IDs.
+
+    Key: "<source_path>|<target_node_path>"
+        where:
+            source_path := "<trigger_module_path>.<TriggerClassName>" for trigger edges
+                          or "<module_path>.<NodeClassName>.Ports.<source_handle_id>"
+                             for node->node edges (handle id disambiguates multiple edges)
+            target_node_path := "<module_path>.<ClassName>.Trigger" for the target node
+    Value: UI edge ID (UUID string)
+    """
+
+    dataset_row_index_to_id_mapping: Dict[str, str] = {}
+    """Mapping of dataset row indices to their UI row IDs.
+
+    Key: Dataset row index (0-based) as a string
+    Value: UI dataset row ID (UUID string)
+    """