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

vellum/workflows/utils/tests/test_functions.py

@@ -1,10 +1,24 @@
+import pytest
 from dataclasses import dataclass
-from typing import Dict, List, Optional, Union
+from enum import Enum
+from unittest.mock import Mock
+from typing import Annotated, Dict, List, Literal, Optional, Tuple, Union
 
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 from vellum.client.types.function_definition import FunctionDefinition
-from vellum.workflows.utils.functions import compile_function_definition
+from vellum.client.types.string_vellum_value import StringVellumValue
+from vellum.client.types.vellum_variable import VellumVariable
+from vellum.workflows import BaseWorkflow
+from vellum.workflows.inputs.base import BaseInputs
+from vellum.workflows.nodes.bases.base import BaseNode
+from vellum.workflows.state.base import BaseState
+from vellum.workflows.types.definition import DeploymentDefinition
+from vellum.workflows.utils.functions import (
+    compile_function_definition,
+    compile_inline_workflow_function_definition,
+    compile_workflow_deployment_function_definition,
+)
 
 
 def test_compile_function_definition__just_name():
@@ -22,6 +36,23 @@ def test_compile_function_definition__just_name():
     )
 
 
+def test_compile_function_definition__docstring():
+    # GIVEN a function with a docstring
+    def my_function():
+        """This is a test function"""
+        pass
+
+    # WHEN compiling the function
+    compiled_function = compile_function_definition(my_function)
+
+    # THEN it should return the compiled function definition
+    assert compiled_function == FunctionDefinition(
+        name="my_function",
+        description="This is a test function",
+        parameters={"type": "object", "properties": {}, "required": []},
+    )
+
+
 def test_compile_function_definition__all_args():
     # GIVEN a function with args of all base types
     def my_function(a: str, b: int, c: float, d: bool, e: list, f: dict):
@@ -176,7 +207,7 @@ def test_compile_function_definition__dataclasses():
 def test_compile_function_definition__pydantic():
     # GIVEN a function with a pydantic model
     class MyPydanticModel(BaseModel):
-        a: int
+        a: int = Field(description="The first number")
         b: str
 
     def my_function(c: MyPydanticModel):
@@ -195,7 +226,10 @@ def test_compile_function_definition__pydantic():
             "$defs": {
                 "MyPydanticModel": {
                     "type": "object",
-                    "properties": {"a": {"type": "integer"}, "b": {"type": "string"}},
+                    "properties": {
+                        "a": {"type": "integer", "description": "The first number"},
+                        "b": {"type": "string"},
+                    },
                     "required": ["a", "b"],
                 }
             },
@@ -262,3 +296,480 @@ def test_compile_function_definition__default_pydantic():
             },
         },
     )
+
+
+def test_compile_function_definition__lambda():
+    # GIVEN a lambda
+    lambda_function = lambda x: x + 1  # noqa: E731
+
+    # WHEN compiling the function
+    compiled_function = compile_function_definition(lambda_function)
+
+    # THEN it should return the compiled function definition
+    assert compiled_function == FunctionDefinition(
+        name="<lambda>",
+        parameters={"type": "object", "properties": {"x": {"type": "null"}}, "required": ["x"]},
+    )
+
+
+def test_compile_inline_workflow_function_definition():
+    class MyNode(BaseNode):
+        pass
+
+    class MyWorkflow(BaseWorkflow):
+        graph = MyNode
+
+    # WHEN compiling the function
+    compiled_function = compile_inline_workflow_function_definition(MyWorkflow)
+
+    # THEN it should return the compiled function definition
+    assert compiled_function == FunctionDefinition(
+        name="my_workflow",
+        parameters={"type": "object", "properties": {}, "required": []},
+    )
+
+
+def test_compile_inline_workflow_function_definition__docstring():
+    class MyNode(BaseNode):
+        pass
+
+    class MyWorkflow(BaseWorkflow):
+        """
+        This is a test workflow
+        """
+
+        graph = MyNode
+
+    # WHEN compiling the function
+    compiled_function = compile_inline_workflow_function_definition(MyWorkflow)
+
+    # THEN it should return the compiled function definition
+    assert compiled_function == FunctionDefinition(
+        name="my_workflow",
+        description="\n        This is a test workflow\n        ",
+        parameters={"type": "object", "properties": {}, "required": []},
+    )
+
+
+def test_compile_inline_workflow_function_definition__all_args():
+    class MyInputs(BaseInputs):
+        a: str
+        b: int
+        c: float
+        d: bool
+        e: list
+        f: dict
+
+    class MyNode(BaseNode):
+        pass
+
+    class MyWorkflow(BaseWorkflow[MyInputs, BaseState]):
+        graph = MyNode
+
+    # WHEN compiling the workflow
+    compiled_function = compile_inline_workflow_function_definition(MyWorkflow)
+
+    # THEN it should return the compiled function definition
+    assert compiled_function == FunctionDefinition(
+        name="my_workflow",
+        parameters={
+            "type": "object",
+            "properties": {
+                "a": {"type": "string"},
+                "b": {"type": "integer"},
+                "c": {"type": "number"},
+                "d": {"type": "boolean"},
+                "e": {"type": "array"},
+                "f": {"type": "object"},
+            },
+            "required": ["a", "b", "c", "d", "e", "f"],
+        },
+    )
+
+
+def test_compile_inline_workflow_function_definition__unions():
+    # GIVEN a workflow with a union
+    class MyInputs(BaseInputs):
+        a: Union[str, int]
+
+    class MyNode(BaseNode):
+        pass
+
+    class MyWorkflow(BaseWorkflow[MyInputs, BaseState]):
+        graph = MyNode
+
+    # WHEN compiling the workflow
+    compiled_function = compile_inline_workflow_function_definition(MyWorkflow)
+
+    # THEN it should return the compiled function definition
+    assert compiled_function == FunctionDefinition(
+        name="my_workflow",
+        parameters={
+            "type": "object",
+            "properties": {"a": {"anyOf": [{"type": "string"}, {"type": "integer"}]}},
+            "required": ["a"],
+        },
+    )
+
+
+def test_compile_inline_workflow_function_definition__optionals():
+    class MyInputs(BaseInputs):
+        a: str
+        b: Optional[str]
+        c: None
+        d: str = "hello"
+        e: Optional[str] = None
+
+    class MyNode(BaseNode):
+        pass
+
+    class MyWorkflow(BaseWorkflow[MyInputs, BaseState]):
+        graph = MyNode
+
+    # WHEN compiling the workflow
+    compiled_function = compile_inline_workflow_function_definition(MyWorkflow)
+
+    # THEN it should return the compiled function definition
+    assert compiled_function == FunctionDefinition(
+        name="my_workflow",
+        parameters={
+            "type": "object",
+            "properties": {
+                "a": {"type": "string"},
+                "b": {"anyOf": [{"type": "string"}, {"type": "null"}]},
+                "c": {"type": "null"},
+                "d": {"type": "string", "default": "hello"},
+                "e": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": None},
+            },
+            "required": ["a", "b", "c"],
+        },
+    )
+
+
+def test_compile_workflow_deployment_function_definition__just_name():
+    # GIVEN a mock Vellum client and deployment
+    mock_client = Mock()
+    mock_release = Mock()
+    mock_release.deployment.name = "my_deployment"
+    mock_release.workflow_version.input_variables = []
+    mock_release.description = "This is a test deployment"
+    mock_client.workflow_deployments.retrieve_workflow_deployment_release.return_value = mock_release
+
+    deployment_definition = DeploymentDefinition(deployment="my_deployment", release_tag="LATEST")
+
+    # WHEN compiling the deployment workflow function
+    compiled_function = compile_workflow_deployment_function_definition(deployment_definition, mock_client)
+
+    # THEN it should return the compiled function definition (same structure as function test)
+    assert compiled_function == FunctionDefinition(
+        name="my_deployment",
+        description="This is a test deployment",
+        parameters={"type": "object", "properties": {}, "required": []},
+    )
+
+
+def test_compile_workflow_deployment_function_definition__all_args():
+    # GIVEN a mock Vellum client and deployment
+    mock_client = Mock()
+    mock_release = Mock()
+
+    mock_inputs = []
+    for key, vellum_type in [
+        ("a", "STRING"),
+        ("b", "NUMBER"),
+        ("c", "JSON"),
+        ("d", "CHAT_HISTORY"),
+        ("e", "SEARCH_RESULTS"),
+        ("f", "ERROR"),
+        ("g", "ARRAY"),
+        ("h", "FUNCTION_CALL"),
+        ("i", "IMAGE"),
+        ("j", "AUDIO"),
+        ("k", "DOCUMENT"),
+        ("l", "NULL"),
+    ]:
+        mock_input = VellumVariable(
+            id=f"input_{key}",
+            key=key,
+            type=vellum_type,
+            required=True,
+            default=None,
+        )
+        mock_inputs.append(mock_input)
+
+    mock_release.workflow_version.input_variables = mock_inputs
+    mock_release.deployment.name = "my_deployment"
+    mock_release.description = "This is a test deployment"
+    mock_client.workflow_deployments.retrieve_workflow_deployment_release.return_value = mock_release
+
+    deployment_definition = DeploymentDefinition(deployment="my_deployment", release_tag="latest")
+
+    # WHEN compiling the deployment workflow function
+    compiled_function = compile_workflow_deployment_function_definition(deployment_definition, mock_client)
+
+    # THEN it should return the compiled function definition
+    assert compiled_function == FunctionDefinition(
+        name="my_deployment",
+        description="This is a test deployment",
+        parameters={
+            "type": "object",
+            "properties": {
+                "a": {"type": "string"},
+                "b": {"type": "number"},
+                "c": {"type": "object"},
+                "d": {"type": "array"},
+                "e": {"type": "array"},
+                "f": {"type": "object"},
+                "g": {"type": "array"},
+                "h": {"type": "object"},
+                "i": {"type": "object"},
+                "j": {"type": "object"},
+                "k": {"type": "object"},
+                "l": {"type": "null"},
+            },
+            "required": ["a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l"],
+        },
+    )
+
+
+def test_compile_workflow_deployment_function_definition__defaults():
+    # GIVEN a mock Vellum client and deployment
+    mock_client = Mock()
+    mock_release = Mock()
+
+    mock_inputs = []
+
+    mock_input_no_default = VellumVariable(
+        id="no_default",
+        key="no_default",
+        type="STRING",
+        required=True,
+        default=None,
+    )
+    mock_inputs.append(mock_input_no_default)
+
+    mock_input_null_default = VellumVariable(
+        id="null_default",
+        key="null_default",
+        type="STRING",
+        required=False,
+        default=StringVellumValue(value=None),
+    )
+    mock_inputs.append(mock_input_null_default)
+
+    mock_input_actual_default = VellumVariable(
+        id="actual_default",
+        key="actual_default",
+        type="STRING",
+        required=False,
+        default=StringVellumValue(value="hello world"),
+    )
+    mock_inputs.append(mock_input_actual_default)
+
+    mock_release.workflow_version.input_variables = mock_inputs
+    mock_release.deployment.name = "my_deployment"
+    mock_release.description = "This is a test deployment"
+    mock_client.workflow_deployments.retrieve_workflow_deployment_release.return_value = mock_release
+
+    deployment_definition = DeploymentDefinition(deployment="my_deployment", release_tag="LATEST")
+
+    # WHEN compiling the deployment workflow function
+    compiled_function = compile_workflow_deployment_function_definition(deployment_definition, mock_client)
+
+    # THEN it should return the compiled function definition with proper default handling
+    assert compiled_function == FunctionDefinition(
+        name="my_deployment",
+        description="This is a test deployment",
+        parameters={
+            "type": "object",
+            "properties": {
+                "no_default": {"type": "string"},
+                "null_default": {"type": "string", "default": None},
+                "actual_default": {"type": "string", "default": "hello world"},
+            },
+            "required": ["no_default"],
+        },
+    )
+
+
+@pytest.mark.parametrize(
+    "annotation,expected_schema",
+    [
+        (Literal["a", "b"], {"type": "string", "enum": ["a", "b"]}),
+        (Literal["a", 1], {"enum": ["a", 1]}),
+    ],
+)
+def test_compile_function_definition__literal(annotation, expected_schema):
+    def my_function(a: annotation):  # type: ignore
+        pass
+
+    compiled_function = compile_function_definition(my_function)
+    assert isinstance(compiled_function.parameters, dict)
+    assert compiled_function.parameters["properties"]["a"] == expected_schema
+
+
+def test_compile_function_definition__literal_type_not_in_map():
+    class MyEnum(Enum):
+        FOO = "foo"
+        BAR = "bar"
+
+    def my_function(a: Literal[MyEnum.FOO, MyEnum.BAR]):
+        pass
+
+    compiled_function = compile_function_definition(my_function)
+    assert isinstance(compiled_function.parameters, dict)
+    assert compiled_function.parameters["properties"]["a"] == {"enum": [MyEnum.FOO, MyEnum.BAR]}
+
+
+def test_compile_function_definition__annotated_descriptions():
+    # GIVEN a function with annotated parameters that include descriptions
+    def my_function(
+        bar: Annotated[str, "My bar parameter"],
+        other: Annotated[int, "My other parameter"],
+        regular_param: str,
+        optional_param: Annotated[bool, "Optional boolean parameter"] = True,
+    ):
+        """Test function with annotated parameters."""
+        pass
+
+    # WHEN compiling the function
+    compiled_function = compile_function_definition(my_function)
+
+    # THEN it should return the compiled function definition with descriptions
+    assert compiled_function == FunctionDefinition(
+        name="my_function",
+        description="Test function with annotated parameters.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "bar": {"type": "string", "description": "My bar parameter"},
+                "other": {"type": "integer", "description": "My other parameter"},
+                "regular_param": {"type": "string"},
+                "optional_param": {"type": "boolean", "description": "Optional boolean parameter", "default": True},
+            },
+            "required": ["bar", "other", "regular_param"],
+        },
+    )
+
+
+def test_compile_function_definition__annotated_without_description():
+    # GIVEN a function with annotated parameters but no description metadata
+    def my_function(param: Annotated[str, None]):
+        pass
+
+    # WHEN compiling the function
+    compiled_function = compile_function_definition(my_function)
+
+    # THEN it should return the compiled function definition without description
+    assert compiled_function == FunctionDefinition(
+        name="my_function",
+        parameters={
+            "type": "object",
+            "properties": {
+                "param": {"type": "string"},
+            },
+            "required": ["param"],
+        },
+    )
+
+
+def test_compile_function_definition__annotated_complex_types():
+    # GIVEN a function with annotated types
+    def my_function(
+        location: Annotated[Literal["New York", "Portland"], "The location you found"],
+        items: Annotated[List[str], "List of string items"],
+        config: Annotated[Dict[str, int], "Configuration mapping"],
+    ):
+        pass
+
+    # WHEN compiling the function
+    compiled_function = compile_function_definition(my_function)
+
+    # THEN it should return the compiled function definition with descriptions for complex types
+    assert compiled_function == FunctionDefinition(
+        name="my_function",
+        parameters={
+            "type": "object",
+            "properties": {
+                "location": {
+                    "type": "string",
+                    "enum": ["New York", "Portland"],
+                    "description": "The location you found",
+                },
+                "items": {"type": "array", "items": {"type": "string"}, "description": "List of string items"},
+                "config": {
+                    "type": "object",
+                    "additionalProperties": {"type": "integer"},
+                    "description": "Configuration mapping",
+                },
+            },
+            "required": ["location", "items", "config"],
+        },
+    )
+
+
+@pytest.mark.parametrize(
+    "annotation,expected_schema",
+    [
+        (
+            Tuple[int, ...],
+            {"type": "array", "items": {"type": "integer"}},
+        ),
+        (
+            Tuple[int, str],
+            {
+                "type": "array",
+                "prefixItems": [{"type": "integer"}, {"type": "string"}],
+                "minItems": 2,
+                "maxItems": 2,
+            },
+        ),
+    ],
+)
+def test_compile_function_definition__tuples(annotation, expected_schema):
+    def my_function(a: annotation):  # type: ignore
+        pass
+
+    compiled_function = compile_function_definition(my_function)
+    assert isinstance(compiled_function.parameters, dict)
+    assert compiled_function.parameters["properties"]["a"] == expected_schema
+
+
+def test_compile_function_definition__string_annotations_with_future_imports():
+    """Test that string annotations work with __future__ import annotations."""
+    # This simulates what happens when using `from __future__ import annotations`
+    # where type annotations become string literals at runtime
+
+    def my_function_with_string_annotations(
+        a: "str",
+        b: "int",
+        c: "float",
+        d: "bool",
+        e: "list",
+        f: "dict",
+        g: "None",
+    ):
+        """Function with string type annotations."""
+        pass
+
+    # WHEN compiling the function
+    compiled_function = compile_function_definition(my_function_with_string_annotations)
+
+    # THEN it should return the compiled function definition with proper types
+    assert compiled_function == FunctionDefinition(
+        name="my_function_with_string_annotations",
+        description="Function with string type annotations.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "a": {"type": "string"},
+                "b": {"type": "integer"},
+                "c": {"type": "number"},
+                "d": {"type": "boolean"},
+                "e": {"type": "array"},
+                "f": {"type": "object"},
+                "g": {"type": "null"},
+            },
+            "required": ["a", "b", "c", "d", "e", "f", "g"],
+        },
+    )

vellum/workflows/utils/tests/test_names.py

@@ -8,6 +8,15 @@ from vellum.workflows.utils.names import pascal_to_title_case
     [
         ("MyPascalCaseString", "My Pascal Case String"),
         ("AnotherPascalCaseString", "Another Pascal Case String"),
+        ("FetchDeploymentScheme", "Fetch Deployment Scheme"),
+        ("CheckDeploymentExists", "Check Deployment Exists"),
+        ("APINode", "API Node"),
+        ("HTTPSConnection", "HTTPS Connection"),
+        ("XMLParser", "XML Parser"),
+        ("SimpleWord", "Simple Word"),
+        ("A", "A"),
+        ("AB", "AB"),
+        ("ABCDef", "ABC Def"),
     ],
 )
 def test_pascal_to_title_case(input_str, expected):

vellum/workflows/utils/tests/test_vellum_variables.py

@@ -1,9 +1,12 @@
 import pytest
 from typing import List, Optional
 
-from vellum import ChatMessage, SearchResult, VellumAudio, VellumDocument, VellumImage
+from vellum import ChatMessage, SearchResult, VellumAudio, VellumDocument, VellumImage, VellumValue
 from vellum.workflows.types.core import Json
-from vellum.workflows.utils.vellum_variables import primitive_type_to_vellum_variable_type
+from vellum.workflows.utils.vellum_variables import (
+    primitive_type_to_vellum_variable_type,
+    vellum_variable_type_to_openapi_type,
+)
 
 
 @pytest.mark.parametrize(
@@ -27,7 +30,34 @@ from vellum.workflows.utils.vellum_variables import primitive_type_to_vellum_var
         (Optional[VellumAudio], "AUDIO"),
         (VellumImage, "IMAGE"),
         (Optional[VellumImage], "IMAGE"),
+        (list[ChatMessage], "CHAT_HISTORY"),
+        (Optional[list[ChatMessage]], "CHAT_HISTORY"),
+        (list[SearchResult], "SEARCH_RESULTS"),
+        (Optional[list[SearchResult]], "SEARCH_RESULTS"),
+        (list[VellumValue], "ARRAY"),
+        (Optional[list[VellumValue]], "ARRAY"),
     ],
 )
 def test_primitive_type_to_vellum_variable_type(type_, expected):
     assert primitive_type_to_vellum_variable_type(type_) == expected
+
+
+@pytest.mark.parametrize(
+    "vellum_type, expected",
+    [
+        ("STRING", "string"),
+        ("NUMBER", "number"),
+        ("JSON", "object"),
+        ("CHAT_HISTORY", "array"),
+        ("SEARCH_RESULTS", "array"),
+        ("ERROR", "object"),
+        ("ARRAY", "array"),
+        ("FUNCTION_CALL", "object"),
+        ("IMAGE", "object"),
+        ("AUDIO", "object"),
+        ("DOCUMENT", "object"),
+        ("NULL", "null"),
+    ],
+)
+def test_vellum_variable_type_to_openapi_type(vellum_type, expected):
+    assert vellum_variable_type_to_openapi_type(vellum_type) == expected

vellum/workflows/utils/uuids.py

@@ -1,5 +1,24 @@
 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:
+    """
+    Generate a workflow deployment prefix from deployment name and release tag.
+
+    Args:
+        deployment_name: The name of the workflow deployment
+        release_tag: The release tag to resolve
+
+    Returns:
+        The generated prefix in format vellum_workflow_deployment_{hash}
+    """
+    expected_hash = str(uuid4_from_hash(f"{deployment_name}|{release_tag}")).replace("-", "_")
+    return f"vellum_workflow_deployment_{expected_hash}"
 
 
 def uuid4_from_hash(input_str: str) -> UUID:
@@ -22,3 +41,19 @@ def uuid4_from_hash(input_str: str) -> UUID:
 
     # Create a UUID from the modified bytes
     return UUID(bytes=bytes(hash_list))
+
+
+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 module name, __qualname__, and attribute name to ensure stability and uniqueness.
+
+    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 module, qualname, and attribute name
+    """
+    trigger_id = trigger_class.__id__
+    return uuid4_from_hash(f"{trigger_id}|{attribute_name}")