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

vellum/workflows/inputs/dataset_row.py

@@ -0,0 +1,186 @@
+from datetime import datetime
+import warnings
+from typing import Any, Callable, Dict, List, Optional, Sequence, Union
+
+from pydantic import ConfigDict, Field, SerializationInfo, field_serializer, model_serializer, model_validator
+
+from vellum.client.core.pydantic_utilities import UniversalBaseModel
+from vellum.utils.files.mixin import VellumFileMixin
+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: Optional Trigger instance for this scenario
+        mocks: Optional sequence of node output mocks for testing scenarios
+    """
+
+    model_config = ConfigDict(populate_by_name=True, arbitrary_types_allowed=True)
+
+    id: Optional[str] = None
+    label: str
+    inputs: Union[BaseInputs, Dict[str, Any]] = Field(default_factory=BaseInputs)
+    workflow_trigger: Optional[BaseTrigger] = None
+    mocks: Optional[Sequence[Union[BaseOutputs, MockNodeExecution]]] = None
+    # DEPRECATED: node_output_mocks - use mocks instead. Remove in v2.0.0
+    node_output_mocks: Optional[Sequence[Union[BaseOutputs, MockNodeExecution]]] = Field(
+        default=None,
+        exclude=True,  # Don't include in serialized output
+    )
+
+    @model_validator(mode="after")
+    def _handle_deprecated_node_output_mocks(self) -> "DatasetRow":
+        """Handle deprecated node_output_mocks field by mapping it to mocks."""
+        if self.node_output_mocks is not None:
+            warnings.warn(
+                "The 'node_output_mocks' parameter is deprecated and will be removed in v2.0.0. "
+                "Please use 'mocks' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            # If mocks is not set, use node_output_mocks value
+            if self.mocks is None:
+                object.__setattr__(self, "mocks", self.node_output_mocks)
+        return self
+
+    @model_serializer(mode="wrap")
+    def serialize_full_model(self, handler: Callable[[Any], Any], info: SerializationInfo) -> Dict[str, Any]:
+        """Serialize the model and add node_id field computed from then_outputs."""
+        serialized = handler(self)
+        if not isinstance(serialized, dict):
+            return serialized
+
+        # Add deprecation error if node_output_mocks was used - remove in v2.0.0
+        if self.node_output_mocks is not None:
+            add_error = info.context.get("add_error") if info.context else None
+            if add_error is not None:
+                add_error(
+                    Exception(
+                        f'Dataset row "{self.label}": "node_output_mocks" is deprecated. '
+                        'Please use "mocks" instead. This will be removed in v2.0.0.'
+                    )
+                )
+
+        if "mocks" in serialized and serialized.get("mocks") is None:
+            serialized.pop("mocks")
+
+        if "workflow_trigger" in serialized:
+            value = serialized.pop("workflow_trigger")
+            if value is not None:
+                serialized["workflow_trigger_id"] = value
+
+        # Merge trigger attribute values into inputs if workflow_trigger is present
+        if self.workflow_trigger is not None:
+            trigger_attrs = self.workflow_trigger.to_trigger_attribute_values()
+            for ref, attr_value in trigger_attrs.items():
+                # Convert datetime objects to ISO format strings for JSON serialization
+                if isinstance(attr_value, datetime):
+                    attr_value = attr_value.isoformat()
+                serialized["inputs"][ref.name] = attr_value
+
+        if "id" in serialized and serialized.get("id") is None:
+            serialized.pop("id")
+
+        return serialized
+
+    @field_serializer("workflow_trigger")
+    def serialize_workflow_trigger(self, workflow_trigger: Optional[BaseTrigger]) -> Optional[str]:
+        """
+        Custom serializer for workflow_trigger that converts it to a string ID.
+
+        Args:
+            workflow_trigger: Optional workflow trigger instance
+
+        Returns:
+            String representation of the trigger ID, or None if no trigger
+        """
+        if workflow_trigger is None:
+            return None
+
+        return str(workflow_trigger.__class__.__id__)
+
+    @field_serializer("inputs")
+    def serialize_inputs(self, inputs: Union[BaseInputs, Dict[str, Any]], info: SerializationInfo) -> Dict[str, Any]:
+        """
+        Custom serializer for inputs that converts it to a dictionary.
+
+        When add_error is provided in the serialization context, this method will
+        validate file-type inputs (VellumFileMixin) by attempting to serialize them,
+        and collect errors for fields that fail to serialize while still including
+        valid fields.
+
+        Args:
+            inputs: Either a BaseInputs instance or dict to serialize
+            info: Serialization info containing context
+
+        Returns:
+            Dictionary representation of the inputs
+        """
+        if isinstance(inputs, dict):
+            return inputs
+
+        result = {}
+        add_error = info.context.get("add_error") if info.context else None
+
+        for input_descriptor, value in inputs:
+            if input_descriptor.name.startswith("__"):
+                continue
+
+            # For file types, validate by attempting to serialize and catch errors
+            if add_error is not None and isinstance(value, VellumFileMixin):
+                try:
+                    # Trigger validation by serializing the file type
+                    value.model_dump(mode="json", by_alias=True, exclude_none=True)
+                    result[input_descriptor.name] = value
+                except Exception as field_error:
+                    error_msg = (
+                        f'Dataset row "{self.label}": input "{input_descriptor.name}" '
+                        f"failed serialization: {field_error}"
+                    )
+                    add_error(Exception(error_msg))
+            else:
+                result[input_descriptor.name] = value
+
+        return result
+
+    @field_serializer("mocks")
+    def serialize_mocks(
+        self, mocks: Optional[Sequence[Union[BaseOutputs, MockNodeExecution]]], info
+    ) -> Optional[List[Dict[str, Any]]]:
+        """
+        Custom serializer for mocks that normalizes both BaseOutputs and MockNodeExecution
+        to a consistent dict format with node_id, when_condition, and then_outputs.
+
+        Args:
+            mocks: Optional sequence of BaseOutputs or MockNodeExecution instances
+            info: Serialization info containing context
+
+        Returns:
+            List of normalized mock execution dicts, or None if input is None
+        """
+        if mocks is None:
+            return None
+
+        result = []
+        for mock in 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(context=info.context))
+
+        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):
@@ -34,7 +84,7 @@ def test_base_inputs_empty_value():
 
     # THEN it should raise a NodeException with the correct error message and code
     assert exc_info.value.code == WorkflowErrorCode.INVALID_INPUTS
-    assert "Required input variables required_string should have defined value" == str(exc_info.value)
+    assert "Required input variables 'required_string' should have defined value" == str(exc_info.value)
 
 
 def test_base_inputs_with_default():
@@ -49,6 +99,115 @@ def test_base_inputs_with_default():
     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):
@@ -62,3 +221,24 @@ def test_base_inputs__supports_inherited_inputs():
     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)