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

vellum/workflows/inputs/base.py

@@ -1,7 +1,8 @@
-from typing import Any, Iterator, Tuple, Type, Union, get_args, get_origin
+from typing import Any, Dict, Iterator, Set, Tuple, Type, Union, get_args, get_origin
 from typing_extensions import dataclass_transform
 
 from pydantic import GetCoreSchemaHandler
+from pydantic.fields import FieldInfo
 from pydantic_core import core_schema
 
 from vellum.workflows.constants import undefined
@@ -14,29 +15,55 @@ from vellum.workflows.types.utils import get_class_attr_names, infer_types
 
 @dataclass_transform(kw_only_default=True)
 class _BaseInputsMeta(type):
+    def __new__(cls, name: str, bases: Tuple[Type, ...], dct: Dict[str, Any]) -> Any:
+        dct["__parent_class__"] = type(None)
+        return super().__new__(cls, name, bases, dct)
+
     def __getattribute__(cls, name: str) -> Any:
-        if not name.startswith("_") and name in cls.__annotations__ and issubclass(cls, BaseInputs):
+        if name.startswith("_") or not issubclass(cls, BaseInputs):
+            return super().__getattribute__(name)
+
+        attr_names = get_class_attr_names(cls)
+        if name in attr_names:
+            # We first try to resolve the instance that this class attribute name is mapped to. If it's not found,
+            # we iterate through its inheritance hierarchy to find the first base class that has this attribute
+            # and use its mapping.
             instance = vars(cls).get(name, undefined)
-            types = infer_types(cls, name)
+            if instance is undefined:
+                for base in cls.__mro__[1:]:
+                    inherited_input_reference = getattr(base, name, undefined)
+                    if isinstance(inherited_input_reference, (ExternalInputReference, WorkflowInputReference)):
+                        instance = inherited_input_reference.instance
+                        break
 
+            types = infer_types(cls, name)
             if getattr(cls, "__descriptor_class__", None) is ExternalInputReference:
                 return ExternalInputReference(name=name, types=types, instance=instance, inputs_class=cls)
             else:
                 return WorkflowInputReference(name=name, types=types, instance=instance, inputs_class=cls)
 
-        return super().__getattribute__(name)
+        if getattr(cls, "__descriptor_class__", None) is ExternalInputReference:
+            return ExternalInputReference(name=name, types=(), instance=undefined, inputs_class=cls)
+        else:
+            return WorkflowInputReference(name=name, types=(), instance=undefined, inputs_class=cls)
 
     def __iter__(cls) -> Iterator[InputReference]:
         # We iterate through the inheritance hierarchy to find all the WorkflowInputReference attached to this
         # Inputs class. __mro__ is the method resolution order, which is the order in which base classes are resolved.
+        yielded_attr_names: Set[str] = set()
+
         for resolved_cls in cls.__mro__:
             attr_names = get_class_attr_names(resolved_cls)
             for attr_name in attr_names:
+                if attr_name in yielded_attr_names:
+                    continue
+
                 attr_value = getattr(resolved_cls, attr_name)
                 if not isinstance(attr_value, (WorkflowInputReference, ExternalInputReference)):
                     continue
 
                 yield attr_value
+                yielded_attr_names.add(attr_name)
 
 
 class BaseInputs(metaclass=_BaseInputsMeta):
@@ -47,7 +74,7 @@ class BaseInputs(metaclass=_BaseInputsMeta):
         Initialize BaseInputs with provided keyword arguments.
 
         Validation logic:
-        1. Ensures all required fields (non-Optional types) either:
+        1. Ensures all required fields (values without defaults, regardless of Optional or not) either:
         - Have a value provided in kwargs, or
         - Have a default value defined in the class
         2. Validates that no None values are provided for required fields
@@ -61,21 +88,47 @@ class BaseInputs(metaclass=_BaseInputsMeta):
         """
         for name, field_type in self.__class__.__annotations__.items():
             # Get the value (either from kwargs or class default)
-            value = kwargs.get(name)
+            value = kwargs.get(name, undefined)
             has_default = name in vars(self.__class__)
 
-            if value is None and not has_default:
-                # Check if field_type allows None
-                origin = get_origin(field_type)
-                args = get_args(field_type)
-                if not (origin is Union and type(None) in args):
-                    raise WorkflowInitializationException(
-                        message=f"Required input variables {name} should have defined value",
-                        code=WorkflowErrorCode.INVALID_INPUTS,
-                    )
-
-            # If value provided in kwargs, set it on the instance
-            if name in kwargs:
+            # If no value provided, check for default
+            if value is undefined and has_default:
+                default_value = vars(self.__class__)[name]
+                # Check if default is a FieldInfo with default_factory
+                if isinstance(default_value, FieldInfo):
+                    if default_value.default_factory is not None:
+                        # Call the factory function to create a new instance
+                        value = default_value.default_factory()  # type: ignore[call-arg]
+                    elif hasattr(default_value, "default") and default_value.default is not ...:
+                        # Use the default value directly
+                        value = default_value.default
+                else:
+                    # Regular default value
+                    value = default_value
+
+            # Check if field_type allows None
+            origin = get_origin(field_type)
+            args = get_args(field_type)
+            is_optional = origin is Union and type(None) in args
+
+            if value is undefined and not has_default:
+                # All fields without defaults must be provided, even if Optional
+                raise WorkflowInitializationException(
+                    message=f"Required input variables {name} should have defined value",
+                    code=WorkflowErrorCode.INVALID_INPUTS,
+                    workflow_definition=self.__class__.__parent_class__,
+                )
+
+            # Validate that None is not provided for non-Optional fields
+            if value is None and not is_optional:
+                raise WorkflowInitializationException(
+                    message=f"Required input variables {name} should have defined value",
+                    code=WorkflowErrorCode.INVALID_INPUTS,
+                    workflow_definition=self.__class__.__parent_class__,
+                )
+
+            # Set the value on the instance (either from kwargs or default)
+            if value is not undefined:
                 setattr(self, name, value)
 
     def __iter__(self) -> Iterator[Tuple[InputReference, Any]]:
@@ -83,6 +136,10 @@ class BaseInputs(metaclass=_BaseInputsMeta):
             if hasattr(self, input_descriptor.name):
                 yield (input_descriptor, getattr(self, input_descriptor.name))
 
+    def __vellum_encode__(self) -> Dict[str, Any]:
+        """Return a JSON-serializable representation of this inputs object."""
+        return {descriptor.name: value for descriptor, value in self if value is not undefined}
+
     @classmethod
     def __get_pydantic_core_schema__(
         cls, source_type: Type[Any], handler: GetCoreSchemaHandler

vellum/workflows/inputs/dataset_row.py

@@ -0,0 +1,81 @@
+from typing import Any, Dict, List, Optional, Sequence, Type, Union
+
+from pydantic import Field, field_serializer
+
+from vellum.client.core.pydantic_utilities import UniversalBaseModel
+from vellum.workflows.inputs.base import BaseInputs
+from vellum.workflows.nodes.mocks import MockNodeExecution
+from vellum.workflows.outputs.base import BaseOutputs
+from vellum.workflows.references.constant import ConstantValueReference
+from vellum.workflows.triggers import BaseTrigger
+
+
+class DatasetRow(UniversalBaseModel):
+    """
+    Universal base model representing a dataset row with a label and inputs.
+
+    Attributes:
+        id: Optional unique identifier for the dataset row
+        label: String label for the dataset row
+        inputs: BaseInputs instance or dict containing the input data
+        workflow_trigger_id: Optional Trigger identifying the workflow trigger class for this scenario
+        node_output_mocks: Optional sequence of node output mocks for testing scenarios
+    """
+
+    id: Optional[str] = None
+    label: str
+    inputs: Union[BaseInputs, Dict[str, Any]] = Field(default_factory=BaseInputs)
+    workflow_trigger: Optional[Type[BaseTrigger]] = None
+    node_output_mocks: Optional[Sequence[Union[BaseOutputs, MockNodeExecution]]] = None
+
+    @field_serializer("inputs")
+    def serialize_inputs(self, inputs: Union[BaseInputs, Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        Custom serializer for inputs that converts it to a dictionary.
+
+        Args:
+            inputs: Either a BaseInputs instance or dict to serialize
+
+        Returns:
+            Dictionary representation of the inputs
+        """
+        if isinstance(inputs, dict):
+            return inputs
+
+        result = {}
+        for input_descriptor, value in inputs:
+            if not input_descriptor.name.startswith("__"):
+                result[input_descriptor.name] = value
+
+        return result
+
+    @field_serializer("node_output_mocks")
+    def serialize_node_output_mocks(
+        self, node_output_mocks: Optional[Sequence[Union[BaseOutputs, MockNodeExecution]]]
+    ) -> Optional[List[Dict[str, Any]]]:
+        """
+        Custom serializer for node_output_mocks that normalizes both BaseOutputs and MockNodeExecution
+        to a consistent dict format with node_id, when_condition, and then_outputs.
+
+        Args:
+            node_output_mocks: Optional sequence of BaseOutputs or MockNodeExecution instances
+
+        Returns:
+            List of normalized mock execution dicts, or None if input is None
+        """
+        if node_output_mocks is None:
+            return None
+
+        result = []
+        for mock in node_output_mocks:
+            if isinstance(mock, MockNodeExecution):
+                mock_exec = mock
+            else:
+                mock_exec = MockNodeExecution(
+                    when_condition=ConstantValueReference(True),
+                    then_outputs=mock,
+                )
+
+            result.append(mock_exec.model_dump())
+
+        return result

vellum/workflows/inputs/tests/test_inputs.py

@@ -1,5 +1,7 @@
 import pytest
-from typing import Optional
+from typing import Any, Optional
+
+from pydantic import Field
 
 from vellum.workflows.errors import WorkflowErrorCode
 from vellum.workflows.exceptions import WorkflowInitializationException
@@ -22,6 +24,54 @@ def test_base_inputs_happy_path():
     assert inputs.optional_string is None
 
 
+def test_base_inputs_explicit_none():
+    """
+    Test that None can be explicitly set as a value, distinguishing it from not providing a value.
+    """
+
+    # GIVEN some input class with optional fields and fields with defaults
+    class TestInputs(BaseInputs):
+        optional_string: Optional[str]
+        optional_string_with_default: Optional[str] = None
+
+    # WHEN we explicitly pass None for optional fields
+    inputs = TestInputs(optional_string=None)
+
+    assert inputs.optional_string is None
+    assert inputs.optional_string_with_default is None
+
+
+@pytest.mark.parametrize("field_type", [str, Optional[str]])
+def test_base_inputs_explicit_none_should_raise_on_fields_without_defaults(field_type):
+    """
+    Test that None cannot be explicitly set as a value for required fields.
+    """
+
+    class TestInputs(BaseInputs):
+        required_string: field_type  # type: ignore[valid-type]
+
+    with pytest.raises(WorkflowInitializationException) as exc_info:
+        TestInputs()  # type: ignore[call-arg]
+
+    assert exc_info.value.code == WorkflowErrorCode.INVALID_INPUTS
+    assert "Required input variables required_string should have defined value" == str(exc_info.value)
+
+
+def test_base_inputs_explicit_none_should_raise_on_required_fields_with_none():
+    """
+    Test that None cannot be explicitly set as a value for required fields.
+    """
+
+    class TestInputs(BaseInputs):
+        required_string: str
+
+    with pytest.raises(WorkflowInitializationException) as exc_info:
+        TestInputs(required_string=None)  # type: ignore[arg-type]
+
+    assert exc_info.value.code == WorkflowErrorCode.INVALID_INPUTS
+    assert "Required input variables required_string should have defined value" == str(exc_info.value)
+
+
 def test_base_inputs_empty_value():
     # GIVEN some input class with required and optional string fields
     class TestInputs(BaseInputs):
@@ -47,3 +97,148 @@ def test_base_inputs_with_default():
 
     # THEN it should use the default value
     assert inputs.string_with_default == "default_value"
+
+
+def test_base_inputs_with_field_default_factory_empty_list():
+    """
+    Test that Field(default_factory=list) works correctly for JSON array inputs.
+    This ensures that each instance gets a separate list instance, avoiding mutable default issues.
+    """
+
+    # GIVEN some input class with Field(default_factory=list) for JSON array
+    class TestInputs(BaseInputs):
+        json_array_input: Any = Field(default_factory=list)  # type: ignore[arg-type]
+        array_input: list[str] = Field(default_factory=list)  # type: ignore[arg-type]
+
+    # WHEN we create two instances without providing values
+    inputs1 = TestInputs()
+    inputs2 = TestInputs()
+
+    # THEN they should get separate list instances
+    assert inputs1.json_array_input is not inputs2.json_array_input
+    assert isinstance(inputs1.json_array_input, list)
+    assert isinstance(inputs2.json_array_input, list)
+
+    # WHEN we modify one instance
+    inputs1.json_array_input.append("test1")
+    inputs2.json_array_input.append("test2")
+
+    # THEN the other instance should be unaffected
+    assert inputs1.json_array_input == ["test1"]
+    assert inputs2.json_array_input == ["test2"]
+
+
+def test_base_inputs_with_field_default_factory_non_empty_list():
+    """
+    Test that Field(default_factory=list) works correctly for non-empty list inputs.
+    """
+
+    # GIVEN some input class with Field(default_factory=list) for non-empty list
+    class TestInputs(BaseInputs):
+        non_empty_list_input: list[str] = Field(default_factory=lambda: ["test1", "test2"])
+
+    # WHEN we create an instance without providing values
+    inputs1 = TestInputs()
+    inputs2 = TestInputs()
+
+    # THEN it should use the default value
+    assert inputs1.non_empty_list_input == ["test1", "test2"]
+    assert inputs2.non_empty_list_input == ["test1", "test2"]
+
+    # WHEN we modify one instance
+    inputs1.non_empty_list_input.append("test3")
+    inputs2.non_empty_list_input.append("test4")
+
+    # THEN the other instance should be unaffected
+    assert inputs1.non_empty_list_input == ["test1", "test2", "test3"]
+    assert inputs2.non_empty_list_input == ["test1", "test2", "test4"]
+
+
+def test_base_inputs_with_field_default_factory_empty_dict():
+    """
+    Test that Field(default_factory=dict) works correctly for JSON dict inputs.
+    This ensures that each instance gets a separate dict instance, avoiding mutable default issues.
+    """
+
+    # GIVEN some input class with Field(default_factory=dict) for JSON dict
+    class TestInputs(BaseInputs):
+        json_dict_input: Any = Field(default_factory=dict)  # type: ignore[arg-type]
+
+    # WHEN we create two instances without providing values
+    inputs1 = TestInputs()
+    inputs2 = TestInputs()
+
+    # THEN they should get separate dict instances
+    assert inputs1.json_dict_input is not inputs2.json_dict_input
+    assert isinstance(inputs1.json_dict_input, dict)
+    assert isinstance(inputs2.json_dict_input, dict)
+
+    # WHEN we modify one instance
+    inputs1.json_dict_input["key1"] = "value1"
+    inputs2.json_dict_input["key2"] = "value2"
+
+    # THEN the other instance should be unaffected
+    assert inputs1.json_dict_input == {"key1": "value1"}
+    assert inputs2.json_dict_input == {"key2": "value2"}
+
+
+def test_base_inputs_with_field_default_factory_non_empty_dict():
+    """
+    Test that Field(default_factory=dict) works correctly for non-empty dict inputs.
+    """
+
+    # GIVEN some input class with Field(default_factory=dict) for non-empty dict
+    class TestInputs(BaseInputs):
+        non_empty_dict_input: dict[str, str] = Field(default_factory=lambda: {"key1": "value1", "key2": "value2"})
+
+    # WHEN we create an instance without providing values
+    inputs1 = TestInputs()
+    inputs2 = TestInputs()
+
+    # THEN it should use the default value
+    assert inputs1.non_empty_dict_input == {"key1": "value1", "key2": "value2"}
+    assert inputs2.non_empty_dict_input == {"key1": "value1", "key2": "value2"}
+
+    # WHEN we modify one instance
+    inputs1.non_empty_dict_input["key3"] = "value3"
+    inputs2.non_empty_dict_input["key4"] = "value4"
+
+    # THEN the other instance should be unaffected
+    assert inputs1.non_empty_dict_input == {"key1": "value1", "key2": "value2", "key3": "value3"}
+    assert inputs2.non_empty_dict_input == {"key1": "value1", "key2": "value2", "key4": "value4"}
+
+
+def test_base_inputs__supports_inherited_inputs():
+    # GIVEN an inputs class
+    class TopInputs(BaseInputs):
+        first: str
+
+    # WHEN we inherit from the base inputs class
+    class BottomInputs(TopInputs):
+        second: int
+
+    # THEN both references should be available
+    assert BottomInputs.first.name == "first"
+    assert BottomInputs.second.name == "second"
+    assert len([ref for ref in BottomInputs]) == 2
+
+
+def test_base_inputs__iterating_over_descriptor_is_finite():
+    """
+    Tests that iterating over a descriptor (like Inputs.image_url) creates a finite generator.
+    This was the bug reported in Slack where AB sometimes generates code that iterates over descriptors.
+    """
+
+    class Inputs(BaseInputs):
+        image_url: str
+
+    iteration_count = 0
+    try:
+        for idx, x in enumerate(Inputs.image_url):  # type: ignore[arg-type,var-annotated]
+            iteration_count += 1
+            if idx > 100:
+                break
+    except (TypeError, IndexError):
+        pass
+
+    assert iteration_count < 100

vellum/workflows/integrations/__init__.py

@@ -0,0 +1,5 @@
+from .composio_service import ComposioService
+from .mcp_service import MCPService
+from .vellum_integration_service import VellumIntegrationService
+
+__all__ = ["ComposioService", "MCPService", "VellumIntegrationService"]

vellum/workflows/integrations/composio_service.py

@@ -0,0 +1,158 @@
+from dataclasses import dataclass
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from vellum.workflows.errors.types import WorkflowErrorCode
+from vellum.workflows.exceptions import NodeException
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ConnectionInfo:
+    """Information about a user's authorized connection"""
+
+    connection_id: str
+    integration_name: str
+    created_at: str
+    updated_at: str
+    status: str = "ACTIVE"
+
+
+class ComposioService:
+    """Composio API client for managing connections and executing tools"""
+
+    def __init__(self, api_key: Optional[str] = None):
+        # If no API key provided, look it up from environment variables
+        if api_key is None:
+            api_key = self._get_api_key_from_env()
+
+        if not api_key:
+            common_env_var_names = ["COMPOSIO_API_KEY", "COMPOSIO_KEY"]
+            raise NodeException(
+                "No Composio API key found. "
+                "Please provide an api_key parameter or set one of these environment variables: "
+                + ", ".join(common_env_var_names)
+            )
+
+        self.api_key = api_key
+        self.base_url = "https://backend.composio.dev/api/v3"
+
+    @staticmethod
+    def _get_api_key_from_env() -> Optional[str]:
+        """Get Composio API key from environment variables"""
+        common_env_var_names = ["COMPOSIO_API_KEY", "COMPOSIO_KEY"]
+
+        for env_var_name in common_env_var_names:
+            value = os.environ.get(env_var_name)
+            if value:
+                return value
+        return None
+
+    def _make_request(
+        self, endpoint: str, method: str = "GET", params: Optional[dict] = None, json_data: Optional[dict] = None
+    ) -> dict:
+        """Make a request to the Composio API"""
+        headers = {
+            "x-api-key": self.api_key,
+            "Content-Type": "application/json",
+        }
+
+        url = f"{self.base_url}{endpoint}"
+
+        try:
+            if method == "GET":
+                response = requests.get(url, headers=headers, params=params or {}, timeout=30)
+            elif method == "POST":
+                response = requests.post(url, headers=headers, json=json_data or {}, timeout=30)
+            else:
+                raise ValueError(f"Unsupported HTTP method: {method}")
+
+            response.raise_for_status()
+            return response.json()
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 401:
+                raise NodeException(
+                    message="Failed to authorize Composio request. Make sure to define a COMPOSIO_API_KEY",
+                    code=WorkflowErrorCode.PROVIDER_CREDENTIALS_UNAVAILABLE,
+                )
+            else:
+                response_text = e.response.text if e.response else "No response"
+                raise NodeException(
+                    f"Composio API request failed with status {e.response.status_code}: {response_text}"
+                )
+        except Exception as e:
+            raise NodeException(f"Composio API request failed: {e}")
+
+    def get_user_connections(self) -> List[ConnectionInfo]:
+        """Get all authorized connections for the user"""
+        response = self._make_request("/connected_accounts")
+
+        return [
+            ConnectionInfo(
+                connection_id=item.get("id"),
+                integration_name=item.get("toolkit", {}).get("slug", ""),
+                status=item.get("status", "ACTIVE"),
+                created_at=item.get("created_at", ""),
+                updated_at=item.get("updated_at", ""),
+            )
+            for item in response.get("items", [])
+        ]
+
+    def get_tool_by_slug(self, tool_slug: str) -> Dict[str, Any]:
+        """Get detailed information about a tool using its slug identifier
+
+        Args:
+            tool_slug: The unique slug identifier of the tool
+
+        Returns:
+            Dictionary containing detailed tool information including:
+            - slug, name, description
+            - toolkit info (slug, name, logo)
+            - input_parameters, output_parameters
+            - no_auth, available_versions, version
+            - scopes, tags, deprecated info
+
+        Raises:
+            NodeException: If tool not found (404), unauthorized (401), or other API errors
+        """
+        endpoint = f"/tools/{tool_slug}"
+
+        try:
+            response = self._make_request(endpoint, method="GET")
+            logger.info(f"Retrieved tool details for slug '{tool_slug}': {response}")
+            return response
+        except Exception as e:
+            # Enhanced error handling for specific cases
+            error_message = str(e)
+            if "404" in error_message:
+                raise NodeException(f"Tool with slug '{tool_slug}' not found in Composio")
+            elif "401" in error_message:
+                raise NodeException(f"Unauthorized access to tool '{tool_slug}'. Check your Composio API key.")
+            else:
+                raise NodeException(f"Failed to retrieve tool details for '{tool_slug}': {error_message}")
+
+    def execute_tool(self, tool_name: str, arguments: Dict[str, Any], user_id: Optional[str] = None) -> Any:
+        """Execute a tool using direct API request
+
+        Args:
+            tool_name: The name of the tool to execute (e.g., "HACKERNEWS_GET_USER")
+            arguments: Dictionary of arguments to pass to the tool
+            user_id: Optional user ID to identify which user's Composio connection to use
+
+        Returns:
+            The result of the tool execution
+        """
+        endpoint = f"/tools/execute/{tool_name}"
+        json_data: Dict[str, Any] = {"arguments": arguments}
+        if user_id is not None:
+            json_data["user_id"] = user_id
+        response = self._make_request(endpoint, method="POST", json_data=json_data)
+
+        if not response.get("successful", True):
+            return response.get("error", "Tool execution failed")
+
+        return response.get("data", response)