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

vellum/workflows/events/workflow.py

@@ -1,16 +1,18 @@
+import logging
 from uuid import UUID
-from typing import TYPE_CHECKING, Any, Dict, Generator, Generic, Iterable, Literal, Optional, Type, Union
+from typing import TYPE_CHECKING, Any, Dict, Generic, Iterable, Literal, Optional, Type, Union, cast
 from typing_extensions import TypeGuard
 
-from pydantic import field_serializer
+from pydantic import SerializationInfo, field_serializer, field_validator
 
-from vellum.core.pydantic_utilities import UniversalBaseModel
+from vellum.client.core.pydantic_utilities import UniversalBaseModel
 from vellum.workflows.errors import WorkflowError
 from vellum.workflows.outputs.base import BaseOutput
 from vellum.workflows.references import ExternalInputReference
-from vellum.workflows.types.definition import serialize_type_encoder_with_id
+from vellum.workflows.types.definition import CodeResourceDefinition, serialize_type_encoder_with_id
 from vellum.workflows.types.generics import InputsType, OutputsType, StateType
 
+from ..triggers import BaseTrigger
 from .node import (
     NodeExecutionFulfilledEvent,
     NodeExecutionInitiatedEvent,
@@ -19,11 +21,36 @@ from .node import (
     NodeExecutionResumedEvent,
     NodeExecutionStreamingEvent,
 )
+from .stream import WorkflowEventGenerator
 from .types import BaseEvent, default_serializer
 
 if TYPE_CHECKING:
+    from vellum.workflows.nodes.bases.base import BaseNode
     from vellum.workflows.workflows.base import BaseWorkflow
 
+logger = logging.getLogger(__name__)
+
+
+def _serialize_body_with_enricher(
+    event: "_BaseWorkflowEvent", body: "_BaseWorkflowExecutionBody", info: SerializationInfo
+) -> "_BaseWorkflowExecutionBody":
+    """
+    Helper function to serialize event body with optional event enrichment.
+
+    This function is used by both WorkflowExecutionInitiatedEvent and WorkflowExecutionFulfilledEvent
+    to apply event enrichment if an event_enricher is provided in the serialization context.
+    """
+    context = info.context if info and hasattr(info, "context") else {}
+    if context and "event_enricher" in context and callable(context["event_enricher"]):
+        try:
+            enriched_event = context["event_enricher"](event)
+            return enriched_event.body
+        except Exception as e:
+            logger.exception(f"Error in event_enricher: {e}")
+            return body
+    else:
+        return body
+
 
 class _BaseWorkflowExecutionBody(UniversalBaseModel):
     workflow_definition: Type["BaseWorkflow"]
@@ -40,6 +67,17 @@ class _BaseWorkflowEvent(BaseEvent):
     def workflow_definition(self) -> Type["BaseWorkflow"]:
         return self.body.workflow_definition
 
+    @property
+    def monitoring_url(self) -> Optional[str]:
+        """
+        Get the monitoring URL for this workflow execution.
+
+        Returns:
+            The URL to view execution details in Vellum UI, or None if monitoring is disabled
+            or context is not available.
+        """
+        return None
+
 
 class NodeEventDisplayContext(UniversalBaseModel):
     input_display: Dict[str, UUID]
@@ -65,6 +103,14 @@ class WorkflowExecutionInitiatedBody(_BaseWorkflowExecutionBody, Generic[InputsT
     # that the Workflow Runner can begin populating this field then.
     display_context: Optional[WorkflowEventDisplayContext] = None
 
+    # This field will be populated during serialization by the serialize_body method
+    workflow_version_exec_config: Optional[Any] = None
+
+    # This field can be populated with arbitrary server metadata during event enrichment
+    server_metadata: Optional[Dict[str, Any]] = None
+
+    trigger: Optional[Type[BaseTrigger]] = None
+
     @field_serializer("inputs")
     def serialize_inputs(self, inputs: InputsType, _info: Any) -> Dict[str, Any]:
         return default_serializer(inputs)
@@ -73,6 +119,12 @@ class WorkflowExecutionInitiatedBody(_BaseWorkflowExecutionBody, Generic[InputsT
     def serialize_initial_state(self, initial_state: Optional[StateType], _info: Any) -> Optional[Dict[str, Any]]:
         return default_serializer(initial_state)
 
+    @field_serializer("trigger")
+    def serialize_trigger(self, trigger: Optional[Type[BaseTrigger]], _info: Any) -> Optional[Dict[str, Any]]:
+        if trigger is None:
+            return None
+        return serialize_type_encoder_with_id(trigger)
+
 
 class WorkflowExecutionInitiatedEvent(_BaseWorkflowEvent, Generic[InputsType, StateType]):
     name: Literal["workflow.execution.initiated"] = "workflow.execution.initiated"
@@ -86,6 +138,14 @@ class WorkflowExecutionInitiatedEvent(_BaseWorkflowEvent, Generic[InputsType, St
     def initial_state(self) -> Optional[StateType]:
         return self.body.initial_state
 
+    @field_serializer("body")
+    def serialize_body(
+        self, body: WorkflowExecutionInitiatedBody[InputsType, StateType], info: SerializationInfo
+    ) -> WorkflowExecutionInitiatedBody[InputsType, StateType]:
+        return cast(
+            WorkflowExecutionInitiatedBody[InputsType, StateType], _serialize_body_with_enricher(self, body, info)
+        )
+
 
 class WorkflowExecutionStreamingBody(_BaseWorkflowExecutionBody):
     output: BaseOutput
@@ -104,25 +164,49 @@ class WorkflowExecutionStreamingEvent(_BaseWorkflowEvent):
         return self.body.output
 
 
-class WorkflowExecutionFulfilledBody(_BaseWorkflowExecutionBody, Generic[OutputsType]):
+class WorkflowExecutionFulfilledBody(_BaseWorkflowExecutionBody, Generic[OutputsType, StateType]):
     outputs: OutputsType
+    final_state: Optional[StateType] = None
+
+    # This field can be populated with arbitrary server metadata during event enrichment
+    server_metadata: Optional[Dict[str, Any]] = None
 
     @field_serializer("outputs")
     def serialize_outputs(self, outputs: OutputsType, _info: Any) -> Dict[str, Any]:
         return default_serializer(outputs)
 
+    @field_serializer("final_state")
+    def serialize_final_state(self, final_state: Optional[StateType], _info: Any) -> Optional[Dict[str, Any]]:
+        if final_state is None:
+            return None
+        state_dict = {k: v for k, v in final_state if k != "meta"}
+        return default_serializer(state_dict)
+
 
-class WorkflowExecutionFulfilledEvent(_BaseWorkflowEvent, Generic[OutputsType]):
+class WorkflowExecutionFulfilledEvent(_BaseWorkflowEvent, Generic[OutputsType, StateType]):
     name: Literal["workflow.execution.fulfilled"] = "workflow.execution.fulfilled"
-    body: WorkflowExecutionFulfilledBody[OutputsType]
+    body: WorkflowExecutionFulfilledBody[OutputsType, StateType]
 
     @property
     def outputs(self) -> OutputsType:
         return self.body.outputs
 
+    @property
+    def final_state(self) -> Optional[StateType]:
+        return self.body.final_state
+
+    @field_serializer("body")
+    def serialize_body(
+        self, body: WorkflowExecutionFulfilledBody[OutputsType, StateType], info: SerializationInfo
+    ) -> WorkflowExecutionFulfilledBody[OutputsType, StateType]:
+        return cast(
+            WorkflowExecutionFulfilledBody[OutputsType, StateType], _serialize_body_with_enricher(self, body, info)
+        )
+
 
 class WorkflowExecutionRejectedBody(_BaseWorkflowExecutionBody):
     error: WorkflowError
+    stacktrace: Optional[str] = None
 
 
 class WorkflowExecutionRejectedEvent(_BaseWorkflowEvent):
@@ -133,6 +217,10 @@ class WorkflowExecutionRejectedEvent(_BaseWorkflowEvent):
     def error(self) -> WorkflowError:
         return self.body.error
 
+    @property
+    def stacktrace(self) -> Optional[str]:
+        return self.body.stacktrace
+
 
 class WorkflowExecutionPausedBody(_BaseWorkflowExecutionBody):
     external_inputs: Iterable[ExternalInputReference]
@@ -158,11 +246,26 @@ class WorkflowExecutionResumedEvent(_BaseWorkflowEvent):
 
 class WorkflowExecutionSnapshottedBody(_BaseWorkflowExecutionBody, Generic[StateType]):
     state: StateType
+    edited_by: Optional[Type["BaseNode"]] = None
+
+    @field_validator("edited_by", mode="before")
+    @classmethod
+    def validate_edited_by(cls, value: Any) -> Any:
+        if value is None:
+            return None
+        value = CodeResourceDefinition.model_validate(value)
+        return value.decode()
 
     @field_serializer("state")
     def serialize_state(self, state: StateType, _info: Any) -> Dict[str, Any]:
         return default_serializer(state)
 
+    @field_serializer("edited_by")
+    def serialize_edited_by(self, edited_by: Optional[Type["BaseNode"]], _info: Any) -> Optional[Dict[str, Any]]:
+        if edited_by is None:
+            return None
+        return serialize_type_encoder_with_id(edited_by)
+
 
 class WorkflowExecutionSnapshottedEvent(_BaseWorkflowEvent, Generic[StateType]):
     name: Literal["workflow.execution.snapshotted"] = "workflow.execution.snapshotted"
@@ -193,7 +296,7 @@ WorkflowEvent = Union[
     WorkflowExecutionSnapshottedEvent,
 ]
 
-WorkflowEventStream = Generator[WorkflowEvent, None, None]
+WorkflowEventStream = WorkflowEventGenerator[WorkflowEvent]
 
 WorkflowExecutionEvent = Union[
     WorkflowExecutionInitiatedEvent,

vellum/workflows/exceptions.py

@@ -1,10 +1,36 @@
+from typing import TYPE_CHECKING, Any, Dict, Optional, Type
+
 from vellum.workflows.errors import WorkflowError, WorkflowErrorCode
 
+if TYPE_CHECKING:
+    from vellum.workflows.workflows.base import BaseWorkflow
+
+
+def import_workflow_class() -> Type["BaseWorkflow"]:
+    """
+    Helper function to help avoid circular imports.
+
+    Ideally, we use the one in types.generics, but _that_ causes circular imports
+    due to the `src/vellum/workflows/types/definition.py` module's import of `EnvironmentVariableReference`
+    """
+
+    from vellum.workflows.workflows import BaseWorkflow
+
+    return BaseWorkflow
+
 
 class NodeException(Exception):
-    def __init__(self, message: str, code: WorkflowErrorCode = WorkflowErrorCode.INTERNAL_ERROR):
+    def __init__(
+        self,
+        message: str,
+        code: WorkflowErrorCode = WorkflowErrorCode.INTERNAL_ERROR,
+        raw_data: Optional[Dict[str, Any]] = None,
+        stacktrace: Optional[str] = None,
+    ):
         self.message = message
         self.code = code
+        self.raw_data = raw_data
+        self.stacktrace = stacktrace
         super().__init__(message)
 
     @property
@@ -12,17 +38,33 @@ class NodeException(Exception):
         return WorkflowError(
             message=self.message,
             code=self.code,
+            raw_data=self.raw_data,
+            stacktrace=self.stacktrace,
         )
 
     @staticmethod
     def of(workflow_error: WorkflowError) -> "NodeException":
-        return NodeException(message=workflow_error.message, code=workflow_error.code)
+        return NodeException(
+            message=workflow_error.message,
+            code=workflow_error.code,
+            raw_data=workflow_error.raw_data,
+            stacktrace=workflow_error.stacktrace,
+        )
 
 
 class WorkflowInitializationException(Exception):
-    def __init__(self, message: str, code: WorkflowErrorCode = WorkflowErrorCode.INVALID_INPUTS):
+    def __init__(
+        self,
+        message: str,
+        workflow_definition: Optional[Type["BaseWorkflow"]] = None,
+        code: WorkflowErrorCode = WorkflowErrorCode.INVALID_INPUTS,
+        raw_data: Optional[Dict[str, Any]] = None,
+    ):
+
         self.message = message
         self.code = code
+        self.raw_data = raw_data
+        self.definition = workflow_definition if workflow_definition is not None else import_workflow_class()
         super().__init__(message)
 
     @property
@@ -30,8 +72,5 @@ class WorkflowInitializationException(Exception):
         return WorkflowError(
             message=self.message,
             code=self.code,
+            raw_data=self.raw_data,
         )
-
-    @staticmethod
-    def of(workflow_error: WorkflowError) -> "WorkflowInitializationException":
-        return WorkflowInitializationException(message=workflow_error.message, code=workflow_error.code)

vellum/workflows/executable.py

@@ -0,0 +1,9 @@
+from uuid import UUID
+from typing import Dict
+
+from vellum.workflows.utils.uuids import uuid4_from_hash
+
+
+class BaseExecutable:
+    __id__: UUID = uuid4_from_hash(__qualname__)
+    __output_ids__: Dict[str, UUID] = {}

vellum/workflows/expressions/accessor.py

@@ -1,16 +1,17 @@
 from collections.abc import Mapping
 import dataclasses
-from typing import Any, Sequence, Type, TypeVar, Union
+from typing import Any, Sequence, Type, TypeVar, Union, get_args, get_origin
 
 from pydantic import BaseModel, GetCoreSchemaHandler
 from pydantic_core import core_schema
 
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.descriptors.exceptions import InvalidExpressionException
-from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.descriptors.utils import is_resolved_instance, resolve_value
 from vellum.workflows.state.base import BaseState
 
 LHS = TypeVar("LHS")
+AccessorField = Union[str, int, BaseDescriptor[str], BaseDescriptor[int]]
 
 
 class AccessorExpression(BaseDescriptor[Any]):
@@ -18,37 +19,90 @@ class AccessorExpression(BaseDescriptor[Any]):
         self,
         *,
         base: BaseDescriptor[LHS],
-        field: Union[str, int],
+        field: AccessorField,
     ) -> None:
         super().__init__(
             name=f"{base.name}.{field}",
-            types=(),
+            types=self._infer_accessor_types(base, field),
             instance=None,
         )
         self._base = base
         self._field = field
 
+    def _infer_accessor_types(self, base: BaseDescriptor[LHS], field: AccessorField) -> tuple[Type, ...]:
+        """
+        Infer the types for this accessor expression based on the base descriptor's types
+        and the field being accessed.
+        """
+        if not base.types:
+            return ()
+
+        inferred_types = []
+
+        for base_type in base.types:
+            origin = get_origin(base_type)
+            args = get_args(base_type)
+
+            if is_resolved_instance(field, int) and origin in (list, tuple) and args:
+                if origin is list:
+                    inferred_types.append(args[0])
+                elif origin is tuple and len(args) == 2 and args[1] is ...:
+                    inferred_types.append(args[0])
+                elif origin is tuple and len(args) > abs(field):
+                    if field >= 0:
+                        inferred_types.append(args[field])
+                    else:
+                        inferred_types.append(args[field])
+            elif is_resolved_instance(field, str) and origin in (dict,) and len(args) >= 2:
+                inferred_types.append(args[1])  # Value type from Dict[K, V]
+
+        return tuple(set(inferred_types)) if inferred_types else ()
+
     def resolve(self, state: "BaseState") -> Any:
         base = resolve_value(self._base, state)
+        accessor_field = resolve_value(self._field, state)
 
         if dataclasses.is_dataclass(base):
-            if isinstance(self._field, int):
+            if isinstance(accessor_field, int):
                 raise InvalidExpressionException("Cannot access field by index on a dataclass")
 
-            return getattr(base, self._field)
+            try:
+                return getattr(base, accessor_field)
+            except AttributeError:
+                raise InvalidExpressionException(
+                    f"Field '{accessor_field}' not found on dataclass {type(base).__name__}"
+                )
 
         if isinstance(base, BaseModel):
-            if isinstance(self._field, int):
+            if isinstance(accessor_field, int):
                 raise InvalidExpressionException("Cannot access field by index on a BaseModel")
 
-            return getattr(base, self._field)
+            try:
+                return getattr(base, accessor_field)
+            except AttributeError:
+                raise InvalidExpressionException(
+                    f"Field '{accessor_field}' not found on BaseModel {type(base).__name__}"
+                )
 
         if isinstance(base, Mapping):
-            return base[self._field]
+            try:
+                return base[accessor_field]
+            except KeyError:
+                raise InvalidExpressionException(f"Key '{accessor_field}' not found in mapping")
 
         if isinstance(base, Sequence):
-            index = int(self._field)
-            return base[index]
+            try:
+                index = int(accessor_field)
+                return base[index]
+            except (IndexError, ValueError):
+                if isinstance(accessor_field, int) or (
+                    isinstance(accessor_field, str) and accessor_field.lstrip("-").isdigit()
+                ):
+                    raise InvalidExpressionException(
+                        f"Index {self._field} is out of bounds for sequence of length {len(base)}"
+                    )
+                else:
+                    raise InvalidExpressionException(f"Invalid index '{self._field}' for sequence access")
 
         raise InvalidExpressionException(f"Cannot get field {self._field} from {base}")
 

vellum/workflows/expressions/add.py

@@ -0,0 +1,41 @@
+from typing import Any, Generic, Protocol, TypeVar, Union, runtime_checkable
+from typing_extensions import TypeGuard
+
+from vellum.workflows.descriptors.base import BaseDescriptor
+from vellum.workflows.descriptors.exceptions import InvalidExpressionException
+from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.state.base import BaseState
+
+
+@runtime_checkable
+class SupportsAdd(Protocol):
+    def __add__(self, other: Any) -> Any: ...
+
+
+def has_add(obj: Any) -> TypeGuard[SupportsAdd]:
+    return hasattr(obj, "__add__")
+
+
+LHS = TypeVar("LHS")
+RHS = TypeVar("RHS")
+
+
+class AddExpression(BaseDescriptor[Any], Generic[LHS, RHS]):
+    def __init__(
+        self,
+        *,
+        lhs: Union[BaseDescriptor[LHS], LHS],
+        rhs: Union[BaseDescriptor[RHS], RHS],
+    ) -> None:
+        super().__init__(name=f"{lhs} + {rhs}", types=(object,))
+        self._lhs = lhs
+        self._rhs = rhs
+
+    def resolve(self, state: "BaseState") -> Any:
+        lhs = resolve_value(self._lhs, state)
+        rhs = resolve_value(self._rhs, state)
+
+        if not has_add(lhs):
+            raise InvalidExpressionException(f"'{lhs.__class__.__name__}' must support the '+' operator")
+
+        return lhs + rhs

vellum/workflows/expressions/comparison_utils.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+
+def try_parse_numeric_string(value: Any) -> Any:
+    """
+    Attempt to parse a string value as a number (int or float).
+
+    This is to support the legacy workflow runner logic where string operands
+    should be automatically parsed as numbers when compared with numeric types.
+
+    Returns the parsed number if successful, otherwise returns the original value.
+    """
+    if not isinstance(value, str):
+        return value
+
+    try:
+        if "." not in value:
+            return int(value)
+        return float(value)
+    except (ValueError, TypeError):
+        return value
+
+
+def prepare_comparison_operands(lhs: Any, rhs: Any) -> tuple[Any, Any]:
+    """
+    Prepare operands for comparison by parsing string operands as numbers when appropriate.
+
+    If one operand is a string and the other is a numeric type (int or float),
+    attempts to parse the string as a number.
+
+    Returns a tuple of (prepared_lhs, prepared_rhs).
+    """
+    if isinstance(lhs, str) and isinstance(rhs, (int, float)):
+        lhs = try_parse_numeric_string(lhs)
+    elif isinstance(rhs, str) and isinstance(lhs, (int, float)):
+        rhs = try_parse_numeric_string(rhs)
+
+    return lhs, rhs

vellum/workflows/expressions/concat.py

@@ -0,0 +1,35 @@
+from typing import Generic, TypeVar, Union
+
+from vellum.workflows.descriptors.base import BaseDescriptor
+from vellum.workflows.descriptors.exceptions import InvalidExpressionException
+from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.state.base import BaseState
+
+LHS = TypeVar("LHS")
+RHS = TypeVar("RHS")
+
+
+class ConcatExpression(BaseDescriptor[list], Generic[LHS, RHS]):
+    def __init__(
+        self,
+        *,
+        lhs: Union[BaseDescriptor[LHS], LHS],
+        rhs: Union[BaseDescriptor[RHS], RHS],
+    ) -> None:
+        super().__init__(name=f"{lhs} + {rhs}", types=(list,))
+        self._lhs = lhs
+        self._rhs = rhs
+
+    def resolve(self, state: "BaseState") -> list:
+        lval = resolve_value(self._lhs, state)
+        rval = resolve_value(self._rhs, state)
+
+        if not isinstance(lval, list):
+            raise InvalidExpressionException(f"Expected LHS to be a list, got {type(lval)}")
+
+        # If RHS is a list, concatenate normally
+        if isinstance(rval, list):
+            return lval + rval
+        # If RHS is not a list, append it as a single item
+        else:
+            return lval + [rval]

vellum/workflows/expressions/contains.py

@@ -35,4 +35,11 @@ class ContainsExpression(BaseDescriptor[bool], Generic[LHS, RHS]):
             )
 
         rhs = resolve_value(self._rhs, state)
+
+        if isinstance(rhs, dict):
+            raise InvalidExpressionException(
+                "Cannot use dict as right-hand side of contains operation. "
+                "Use dict keys/values or convert to strings for comparison."
+            )
+
         return rhs in lhs

vellum/workflows/expressions/greater_than.py

@@ -4,6 +4,7 @@ from typing_extensions import TypeGuard
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.descriptors.exceptions import InvalidExpressionException
 from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.expressions.comparison_utils import prepare_comparison_operands
 from vellum.workflows.state.base import BaseState
 
 
@@ -35,7 +36,13 @@ class GreaterThanExpression(BaseDescriptor[bool], Generic[LHS, RHS]):
         lhs = resolve_value(self._lhs, state)
         rhs = resolve_value(self._rhs, state)
 
+        # Parse string operands as numbers when comparing with numeric types
+        lhs, rhs = prepare_comparison_operands(lhs, rhs)
+
         if not has_gt(lhs):
             raise InvalidExpressionException(f"'{lhs.__class__.__name__}' must support the '>' operator")
 
-        return lhs > rhs
+        try:
+            return lhs > rhs
+        except TypeError as e:
+            raise InvalidExpressionException(str(e))

vellum/workflows/expressions/greater_than_or_equal_to.py

@@ -4,6 +4,7 @@ from typing_extensions import TypeGuard
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.descriptors.exceptions import InvalidExpressionException
 from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.expressions.comparison_utils import prepare_comparison_operands
 from vellum.workflows.state.base import BaseState
 
 LHS = TypeVar("LHS")
@@ -34,7 +35,13 @@ class GreaterThanOrEqualToExpression(BaseDescriptor[bool], Generic[LHS, RHS]):
         lhs = resolve_value(self._lhs, state)
         rhs = resolve_value(self._rhs, state)
 
+        # Parse string operands as numbers when comparing with numeric types
+        lhs, rhs = prepare_comparison_operands(lhs, rhs)
+
         if not has_ge(lhs):
             raise InvalidExpressionException(f"'{lhs.__class__.__name__}' must support the '>=' operator")
 
-        return lhs >= rhs
+        try:
+            return lhs >= rhs
+        except TypeError as e:
+            raise InvalidExpressionException(str(e))

vellum/workflows/expressions/is_error.py

@@ -0,0 +1,23 @@
+from typing import Generic, TypeVar, Union
+
+from vellum.client.types.vellum_error import VellumError
+from vellum.workflows.descriptors.base import BaseDescriptor
+from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.errors.types import WorkflowError
+from vellum.workflows.state.base import BaseState
+
+_T = TypeVar("_T")
+
+
+class IsErrorExpression(BaseDescriptor[bool], Generic[_T]):
+    def __init__(
+        self,
+        *,
+        expression: Union[BaseDescriptor[_T], _T],
+    ) -> None:
+        super().__init__(name=f"{expression} is error", types=(bool,))
+        self._expression = expression
+
+    def resolve(self, state: "BaseState") -> bool:
+        expression = resolve_value(self._expression, state)
+        return isinstance(expression, (VellumError, WorkflowError))

vellum/workflows/expressions/length.py

@@ -0,0 +1,46 @@
+from typing import Any, Generic, Protocol, TypeVar, Union, runtime_checkable
+from typing_extensions import TypeGuard
+
+from vellum.workflows.constants import undefined
+from vellum.workflows.descriptors.base import BaseDescriptor
+from vellum.workflows.descriptors.exceptions import InvalidExpressionException
+from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.state.base import BaseState
+
+
+@runtime_checkable
+class SupportsLen(Protocol):
+    def __len__(self) -> int: ...
+
+
+def has_len(obj: Any) -> TypeGuard[SupportsLen]:
+    return hasattr(obj, "__len__")
+
+
+_T = TypeVar("_T")
+
+
+class LengthExpression(BaseDescriptor[int], Generic[_T]):
+    def __init__(
+        self,
+        *,
+        expression: Union[BaseDescriptor[_T], _T],
+    ) -> None:
+        super().__init__(name=f"length({expression})", types=(int,))
+        self._expression = expression
+
+    def resolve(self, state: "BaseState") -> int:
+        expression = resolve_value(self._expression, state)
+
+        if expression is undefined:
+            raise InvalidExpressionException("Cannot get length of undefined value")
+
+        if not has_len(expression):
+            raise InvalidExpressionException(
+                f"Expected an object that supports `len()`, got `{expression.__class__.__name__}`"
+            )
+
+        try:
+            return len(expression)
+        except TypeError as e:
+            raise InvalidExpressionException(f"Cannot get length of `{expression.__class__.__name__}`: {str(e)}")