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

vellum/workflows/types/definition.py

@@ -2,11 +2,19 @@ import importlib
 import inspect
 from types import FrameType
 from uuid import UUID
-from typing import Annotated, Any, Dict, Optional, Union
+from typing import TYPE_CHECKING, Annotated, Any, Callable, Dict, List, Literal, Optional, Type, Union
 
-from pydantic import BeforeValidator
+from pydantic import BeforeValidator, SerializationInfo, model_serializer
 
+from vellum import Vellum
+from vellum.client.core.pydantic_utilities import UniversalBaseModel
 from vellum.client.types.code_resource_definition import CodeResourceDefinition as ClientCodeResourceDefinition
+from vellum.client.types.vellum_variable import VellumVariable
+from vellum.workflows.constants import AuthorizationType, VellumIntegrationProviderType
+from vellum.workflows.references.environment_variable import EnvironmentVariableReference
+
+if TYPE_CHECKING:
+    from vellum.workflows.workflows.base import BaseWorkflow
 
 
 def serialize_type_encoder(obj: type) -> Dict[str, Any]:
@@ -21,6 +29,11 @@ def serialize_type_encoder_with_id(obj: Union[type, "CodeResourceDefinition"]) -
         return {
             "id": getattr(obj, "__id__"),
             **serialize_type_encoder(obj),
+            **(
+                {"exclude_from_monitoring": getattr(obj, "__exclude_from_monitoring__")}
+                if hasattr(obj, "__exclude_from_monitoring__")
+                else {}
+            ),
         }
     elif isinstance(obj, CodeResourceDefinition):
         return obj.model_dump(mode="json")
@@ -69,3 +82,156 @@ VellumCodeResourceDefinition = Annotated[
     CodeResourceDefinition,
     BeforeValidator(lambda d: (d if type(d) is dict else serialize_type_encoder_with_id(d))),
 ]
+
+
+class DeploymentDefinition(UniversalBaseModel):
+    deployment: str
+    release_tag: str = "LATEST"
+
+    # hydrated fields
+    name: Optional[str] = None
+    description: Optional[str] = None
+    input_variables: Optional[List[VellumVariable]] = None
+
+    def _is_uuid(self) -> bool:
+        """Check if the deployment field is a valid UUID."""
+        try:
+            UUID(self.deployment)
+            return True
+        except ValueError:
+            return False
+
+    @property
+    def deployment_id(self) -> Optional[UUID]:
+        """Get the deployment ID if the deployment field is a UUID."""
+        if self._is_uuid():
+            return UUID(self.deployment)
+        return None
+
+    @property
+    def deployment_name(self) -> Optional[str]:
+        """Get the deployment name if the deployment field is not a UUID."""
+        if not self._is_uuid():
+            return self.deployment
+        return None
+
+    def get_release_info(self, client: Vellum):
+        try:
+            release = client.workflow_deployments.retrieve_workflow_deployment_release(
+                self.deployment, self.release_tag
+            )
+        except Exception:
+            # If we fail to get the release info, we'll use the deployment name and description
+            return {
+                "name": self.deployment,
+                "description": f"Workflow Deployment for {self.deployment}",
+                "input_variables": [],
+            }
+
+        return {
+            "name": release.deployment.name,
+            "description": release.description or f"Workflow Deployment for {self.deployment}",
+            "input_variables": release.workflow_version.input_variables,
+        }
+
+    @model_serializer(mode="wrap")
+    def _serialize(self, handler, info: SerializationInfo):
+        """Allow Pydantic to serialize directly given a `client` in context.
+
+        Falls back to the default serialization when client is not provided.
+        """
+        context = info.context if info and hasattr(info, "context") else {}
+        client: Optional[Vellum] = context.get("client") if context else None
+
+        if client:
+            release_info = self.get_release_info(client)
+            return {
+                "type": "WORKFLOW_DEPLOYMENT",
+                "name": release_info["name"],
+                "description": release_info["description"],
+                "deployment": self.deployment,
+                "release_tag": self.release_tag,
+            }
+
+        return handler(self)
+
+
+class ComposioToolDefinition(UniversalBaseModel):
+    """Represents a specific Composio action that can be used in Tool Calling Node"""
+
+    type: Literal["COMPOSIO"] = "COMPOSIO"
+
+    # Core identification
+    toolkit: str  # "GITHUB", "SLACK", etc.
+    action: str  # Specific action like "GITHUB_CREATE_AN_ISSUE"
+    description: str
+    user_id: Optional[str] = None
+    name: str = ""
+
+    def model_post_init(self, __context: Any):
+        if self.name == "":
+            self.name = self.action.lower()
+
+
+class VellumIntegrationToolDefinition(UniversalBaseModel):
+    type: Literal["VELLUM_INTEGRATION"] = "VELLUM_INTEGRATION"
+
+    # Core identification
+    provider: VellumIntegrationProviderType
+    integration_name: str  # "GITHUB", "SLACK", etc.
+    name: str  # Specific action like "GITHUB_CREATE_AN_ISSUE"
+
+    # Required for tool base consistency
+    description: str
+
+
+class VellumIntegrationToolDetails(VellumIntegrationToolDefinition):
+    """Extended version of VellumIntegrationToolDefinition with runtime parameters.
+
+    This class includes the parameters field which is populated during compilation
+    from the Vellum integrations API response. It inherits all fields from the base
+    VellumIntegrationToolDefinition class.
+    """
+
+    parameters: Optional[Dict[str, Any]] = None
+
+
+class MCPServer(UniversalBaseModel):
+    type: Literal["MCP_SERVER"] = "MCP_SERVER"
+    name: str
+    description: str = ""  # We don't use this field, its for compatibility with UI
+    url: str
+    authorization_type: Optional[AuthorizationType] = None
+    bearer_token_value: Optional[Union[str, EnvironmentVariableReference]] = None
+    api_key_header_key: Optional[str] = None
+    api_key_header_value: Optional[Union[str, EnvironmentVariableReference]] = None
+
+    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
+    server: MCPServer
+    description: Optional[str] = None
+    parameters: Dict[str, Any] = {}
+
+
+# Type alias for functions that can be called in tool calling nodes
+ToolBase = Union[
+    Callable[..., Any],
+    DeploymentDefinition,
+    Type["BaseWorkflow"],
+    ComposioToolDefinition,
+    VellumIntegrationToolDefinition,
+]
+Tool = Union[ToolBase, MCPServer]

vellum/workflows/types/generics.py

@@ -42,6 +42,11 @@ def is_node_class(obj: Any) -> TypeGuard[Type["BaseNode"]]:
     return isinstance(obj, type) and issubclass(obj, base_node_class)
 
 
+def is_node_instance(obj: Any) -> TypeGuard["BaseNode"]:
+    base_node_class = _import_node_class()
+    return isinstance(obj, base_node_class)
+
+
 def is_workflow_class(obj: Any) -> TypeGuard[Type["BaseWorkflow"]]:
     base_workflow_class = import_workflow_class()
     return isinstance(obj, type) and issubclass(obj, base_workflow_class)

vellum/workflows/types/tests/test_definition.py

@@ -0,0 +1,183 @@
+import pytest
+from uuid import UUID
+
+from vellum.workflows.constants import AuthorizationType, VellumIntegrationProviderType
+from vellum.workflows.references.environment_variable import EnvironmentVariableReference
+from vellum.workflows.types.definition import (
+    ComposioToolDefinition,
+    DeploymentDefinition,
+    MCPServer,
+    MCPToolDefinition,
+    VellumIntegrationToolDefinition,
+)
+
+
+@pytest.mark.parametrize(
+    "deployment_value, expected_deployment_id, expected_deployment_name",
+    [
+        # Valid UUID string
+        (
+            "57f09beb-b463-40e0-bf9e-c972e664352f",
+            UUID("57f09beb-b463-40e0-bf9e-c972e664352f"),
+            None,
+        ),
+        # Name string
+        (
+            "tool-calling-subworkflow",
+            None,
+            "tool-calling-subworkflow",
+        ),
+    ],
+    ids=[
+        "valid_uuid",
+        "valid_name",
+    ],
+)
+def test_deployment_definition(deployment_value, expected_deployment_id, expected_deployment_name):
+    """Test that DeploymentDefinition properties correctly identify and extract UUID vs name."""
+    deployment = DeploymentDefinition(deployment=deployment_value)
+
+    assert deployment.deployment_id == expected_deployment_id
+    assert deployment.deployment_name == expected_deployment_name
+
+
+def test_composio_tool_definition_creation():
+    """Test that ComposioToolDefinition can be created with required fields."""
+    composio_tool = ComposioToolDefinition(
+        toolkit="GITHUB",
+        action="GITHUB_CREATE_AN_ISSUE",
+        description="Create a new issue in a GitHub repository",
+        user_id=None,
+    )
+
+    assert composio_tool.toolkit == "GITHUB"
+    assert composio_tool.action == "GITHUB_CREATE_AN_ISSUE"
+    assert composio_tool.description == "Create a new issue in a GitHub repository"
+    assert composio_tool.user_id is None
+    assert composio_tool.name == "github_create_an_issue"
+
+
+def test_mcp_tool_definition_creation_bearer_token():
+    """Test that MCPToolDefinition can be created with required fields."""
+    mcp_tool = MCPToolDefinition(
+        name="create_repository",
+        server=MCPServer(
+            name="github",
+            url="https://api.githubcopilot.com/mcp/",
+            authorization_type=AuthorizationType.BEARER_TOKEN,
+            bearer_token_value=EnvironmentVariableReference(name="GITHUB_PERSONAL_ACCESS_TOKEN"),
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "repository_name": {"type": "string", "description": "Repository name"},
+                "description": {"type": "string", "description": "Repository description"},
+            },
+            "required": ["repository_name"],
+        },
+    )
+
+    assert mcp_tool.name == "create_repository"
+    assert mcp_tool.server.name == "github"
+    assert mcp_tool.server.url == "https://api.githubcopilot.com/mcp/"
+    assert mcp_tool.server.authorization_type == AuthorizationType.BEARER_TOKEN
+    assert mcp_tool.parameters == {
+        "type": "object",
+        "properties": {
+            "repository_name": {"type": "string", "description": "Repository name"},
+            "description": {"type": "string", "description": "Repository description"},
+        },
+        "required": ["repository_name"],
+    }
+
+    assert isinstance(mcp_tool.server.bearer_token_value, EnvironmentVariableReference)
+    assert mcp_tool.server.bearer_token_value.name == "GITHUB_PERSONAL_ACCESS_TOKEN"
+
+
+def test_mcp_tool_definition_creation_api_key():
+    """Test that MCPToolDefinition can be created with required fields."""
+    mcp_tool = MCPToolDefinition(
+        name="create_repository",
+        server=MCPServer(
+            name="github",
+            url="https://api.githubcopilot.com/mcp/",
+            authorization_type=AuthorizationType.API_KEY,
+            api_key_header_key="Authorization",
+            api_key_header_value=EnvironmentVariableReference(name="GITHUB_PERSONAL_ACCESS_TOKEN"),
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "repository_name": {"type": "string", "description": "Repository name"},
+                "description": {"type": "string", "description": "Repository description"},
+            },
+            "required": ["repository_name"],
+        },
+    )
+
+    assert mcp_tool.name == "create_repository"
+    assert mcp_tool.server.name == "github"
+    assert mcp_tool.server.url == "https://api.githubcopilot.com/mcp/"
+    assert mcp_tool.server.authorization_type == AuthorizationType.API_KEY
+    assert mcp_tool.server.api_key_header_key == "Authorization"
+    assert isinstance(mcp_tool.server.api_key_header_value, EnvironmentVariableReference)
+    assert mcp_tool.server.api_key_header_value.name == "GITHUB_PERSONAL_ACCESS_TOKEN"
+    assert mcp_tool.parameters == {
+        "type": "object",
+        "properties": {
+            "repository_name": {"type": "string", "description": "Repository name"},
+            "description": {"type": "string", "description": "Repository description"},
+        },
+        "required": ["repository_name"],
+    }
+
+
+def test_mcp_tool_definition_creation_no_authorization():
+    """Test that MCPToolDefinition can be created with no authorization."""
+    mcp_tool = MCPToolDefinition(
+        name="create_repository",
+        server=MCPServer(
+            name="github",
+            url="https://api.githubcopilot.com/mcp/",
+        ),
+    )
+
+    assert mcp_tool.name == "create_repository"
+    assert mcp_tool.server.name == "github"
+    assert mcp_tool.server.url == "https://api.githubcopilot.com/mcp/"
+    assert mcp_tool.server.authorization_type is None
+    assert mcp_tool.server.bearer_token_value is None
+    assert mcp_tool.server.api_key_header_key is None
+    assert mcp_tool.server.api_key_header_value is None
+
+
+def test_vellum_integration_tool_definition_creation():
+    """Test that VellumIntegrationToolDefinition can be created with required fields."""
+    vellum_tool = VellumIntegrationToolDefinition(
+        provider=VellumIntegrationProviderType.COMPOSIO,
+        integration_name="GITHUB",
+        name="create_issue",
+        description="Create a new issue in a GitHub repository",
+    )
+
+    assert vellum_tool.type == "VELLUM_INTEGRATION"
+    assert vellum_tool.provider == VellumIntegrationProviderType.COMPOSIO
+    assert vellum_tool.integration_name == "GITHUB"
+    assert vellum_tool.name == "create_issue"
+    assert vellum_tool.description == "Create a new issue in a GitHub repository"
+
+
+def test_vellum_integration_tool_definition_with_different_provider():
+    """Test VellumIntegrationToolDefinition with a different provider."""
+    vellum_tool = VellumIntegrationToolDefinition(
+        provider=VellumIntegrationProviderType.COMPOSIO,
+        integration_name="SLACK",
+        name="send_message",
+        description="Send a message to a Slack channel",
+    )
+
+    assert vellum_tool.type == "VELLUM_INTEGRATION"
+    assert vellum_tool.provider == VellumIntegrationProviderType.COMPOSIO
+    assert vellum_tool.integration_name == "SLACK"
+    assert vellum_tool.name == "send_message"
+    assert vellum_tool.description == "Send a message to a Slack channel"

vellum/workflows/types/tests/test_utils.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import pytest
 from typing import Any, ClassVar, Generic, List, TypeVar, Union
 
@@ -24,6 +26,11 @@ class ExampleClass:
     mu: list[str]
 
 
+class ExamplePEP604Class:
+    pep604_union: str | int
+    pep604_optional: str | None
+
+
 T = TypeVar("T")
 
 
@@ -58,6 +65,8 @@ class ExampleNode(BaseNode):
         (ExampleNode.Outputs, "iota", (str,)),
         (ExampleClass, "kappa", (Any,)),
         (ExampleClass, "mu", (list[str],)),
+        (ExamplePEP604Class, "pep604_union", (str, int)),
+        (ExamplePEP604Class, "pep604_optional", (str, type(None))),
     ],
     ids=[
         "str",
@@ -74,6 +83,8 @@ class ExampleNode(BaseNode):
         "try_node_output",
         "any",
         "list_str_generic",
+        "pep604_union",
+        "pep604_optional",
     ],
 )
 def test_infer_types(cls, attr_name, expected_type):
@@ -83,9 +94,9 @@ def test_infer_types(cls, attr_name, expected_type):
 @pytest.mark.parametrize(
     "cls, expected_attr_names",
     [
-        (ExampleClass, {"alpha", "beta", "gamma", "epsilon", "zeta", "eta", "kappa", "mu"}),
-        (ExampleGenericClass, {"delta"}),
-        (ExampleInheritedClass, {"alpha", "beta", "gamma", "epsilon", "zeta", "eta", "theta", "kappa", "mu"}),
+        (ExampleClass, ["beta", "epsilon", "alpha", "gamma", "zeta", "eta", "kappa", "mu"]),
+        (ExampleGenericClass, ["delta"]),
+        (ExampleInheritedClass, ["theta", "beta", "epsilon", "alpha", "gamma", "zeta", "eta", "kappa", "mu"]),
     ],
 )
 def test_class_attr_names(cls, expected_attr_names):

vellum/workflows/types/utils.py

@@ -1,3 +1,4 @@
+import builtins
 from copy import deepcopy
 from datetime import datetime
 import importlib
@@ -7,6 +8,7 @@ from typing import (
     ClassVar,
     Dict,
     Generic,
+    List,
     Optional,
     Set,
     Tuple,
@@ -20,6 +22,7 @@ from typing import (
 )
 
 from vellum import ArrayVellumValue, ArrayVellumValueRequest, ChatMessagePromptBlock
+from vellum.workflows.constants import undefined
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.types.core import Json, SpecialGenericAlias, UnderGenericAlias, UnionGenericAlias
 
@@ -48,9 +51,12 @@ def resolve_combined_types(
     lhs_types = resolve_types(lhs)
     rhs_types = resolve_types(rhs)
 
-    unique_results = set(lhs_types) | set(rhs_types)
+    result_types: List[Union[Type[_LHS], Type[_RHS]]] = list(lhs_types)
+    for rhs_type in rhs_types:
+        if rhs_type not in result_types:
+            result_types.append(rhs_type)
 
-    return tuple(unique_results)
+    return tuple(result_types)
 
 
 def infer_types(object_: Type, attr_name: str, localns: Optional[Dict[str, Any]] = None) -> Tuple[Type, ...]:
@@ -64,6 +70,27 @@ def infer_types(object_: Type, attr_name: str, localns: Optional[Dict[str, Any]]
                 args = get_args(object_)
                 type_var_mapping = {t: a for t, a in zip(origin.__parameters__, args)}
 
+        if hasattr(object_, "__annotations__") and attr_name in object_.__annotations__:
+            annotation_str = object_.__annotations__[attr_name]
+            if isinstance(annotation_str, str) and "|" in annotation_str:
+                parts = [part.strip() for part in annotation_str.split("|")]
+                types_list: List[Type] = []
+                for part in parts:
+                    if part == "None":
+                        types_list.append(type(None))
+                    else:
+                        try:
+                            module = importlib.import_module(object_.__module__)
+                            resolved_type = getattr(module, part, None)
+                            if resolved_type is None:
+                                resolved_type = getattr(builtins, part, None)
+                            if resolved_type is not None and isinstance(resolved_type, type):
+                                types_list.append(resolved_type)
+                        except (ImportError, AttributeError):
+                            pass
+                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})
         if attr_name in type_hints:
             type_hint = type_hints[attr_name]
@@ -96,27 +123,51 @@ def infer_types(object_: Type, attr_name: str, localns: Optional[Dict[str, Any]]
 
         raise AttributeError(f"Failed to infer type from attribute {attr_name} on {object_.__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)
         raise AttributeError(
-            f"Found 3.9+ typing syntax for field '{attr_name}' on class '{object_.__name__}' – {object_.__annotations__[attr_name]}. Type annotations must be compatible with python version 3.8. "  # noqa: E501
+            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
         )
 
 
-def get_class_attr_names(cls: Type) -> Set[str]:
-    # gets type-annotated attributes `foo: int`
-    type_annotated_attributes: Set[str] = set()
+def get_class_attr_names(cls: Type) -> List[str]:
+    # make sure we don't duplicate attributes
+    collected_attributes: Set[str] = set()
+
+    # we want to preserve the order of attributes on each class
+    ordered_attr_names: List[str] = []
+
+    for base in cls.__mro__:
+        # gets attributes declared `foo = 1`
+        for class_attribute in vars(base).keys():
+            if class_attribute in collected_attributes:
+                continue
 
-    # gets attributes declared `foo = 1`
-    class_attributes: Set[str] = set()
+            if class_attribute.startswith("_"):
+                continue
 
-    for base in reversed(cls.__mro__):
+            collected_attributes.add(class_attribute)
+            ordered_attr_names.append(class_attribute)
+
+        # gets type-annotated attributes `foo: int`
         ann = base.__dict__.get("__annotations__", {})
-        type_annotated_attributes.update(ann.keys())
+        for attr_name in ann.keys():
+            if not isinstance(attr_name, str):
+                continue
+
+            if attr_name in collected_attributes:
+                continue
+
+            if attr_name.startswith("_"):
+                continue
 
-        base_vars = vars(base).keys()
-        class_attributes.update(base_vars)
+            collected_attributes.add(attr_name)
+            ordered_attr_names.append(attr_name)
 
     # combine and filter out private attributes
-    return {a for a in list(set(class_attributes) | set(type_annotated_attributes)) if not a.startswith("_")}
+    return ordered_attr_names
 
 
 def deepcopy_with_exclusions(

vellum/workflows/utils/files.py

@@ -0,0 +1,28 @@
+"""File utilities for workflows, including virtual file support."""
+
+import sys
+
+from vellum.workflows.loaders.base import BaseWorkflowFinder
+
+
+def virtual_open(file_path: str):
+    """
+    Open a file, checking BaseWorkflowFinder instances first before falling back to regular open().
+
+    This function is used to support reading files in both regular and virtual environments
+    (e.g., when using VirtualFileLoader in serverless/Vembda deployments).
+
+    Args:
+        file_path: Path to the file to open
+
+    Returns:
+        A file-like object (either StringIO or a regular file handle)
+    """
+    # Check if there's a BaseWorkflowFinder in sys.meta_path
+    for finder in sys.meta_path:
+        if isinstance(finder, BaseWorkflowFinder):
+            result = finder.virtual_open(file_path)
+            if result is not None:
+                return result
+
+    return open(file_path)