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

vellum/workflows/descriptors/base.py

@@ -2,10 +2,12 @@ from typing import TYPE_CHECKING, Any, Generic, Optional, Tuple, Type, TypeVar,
 
 if TYPE_CHECKING:
     from vellum.workflows.expressions.accessor import AccessorExpression
+    from vellum.workflows.expressions.add import AddExpression
     from vellum.workflows.expressions.and_ import AndExpression
     from vellum.workflows.expressions.begins_with import BeginsWithExpression
     from vellum.workflows.expressions.between import BetweenExpression
     from vellum.workflows.expressions.coalesce_expression import CoalesceExpression
+    from vellum.workflows.expressions.concat import ConcatExpression
     from vellum.workflows.expressions.contains import ContainsExpression
     from vellum.workflows.expressions.does_not_begin_with import DoesNotBeginWithExpression
     from vellum.workflows.expressions.does_not_contain import DoesNotContainExpression
@@ -17,6 +19,7 @@ if TYPE_CHECKING:
     from vellum.workflows.expressions.greater_than_or_equal_to import GreaterThanOrEqualToExpression
     from vellum.workflows.expressions.in_ import InExpression
     from vellum.workflows.expressions.is_blank import IsBlankExpression
+    from vellum.workflows.expressions.is_error import IsErrorExpression
     from vellum.workflows.expressions.is_nil import IsNilExpression
     from vellum.workflows.expressions.is_not_blank import IsNotBlankExpression
     from vellum.workflows.expressions.is_not_nil import IsNotNilExpression
@@ -24,8 +27,10 @@ if TYPE_CHECKING:
     from vellum.workflows.expressions.is_not_undefined import IsNotUndefinedExpression
     from vellum.workflows.expressions.is_null import IsNullExpression
     from vellum.workflows.expressions.is_undefined import IsUndefinedExpression
+    from vellum.workflows.expressions.length import LengthExpression
     from vellum.workflows.expressions.less_than import LessThanExpression
     from vellum.workflows.expressions.less_than_or_equal_to import LessThanOrEqualToExpression
+    from vellum.workflows.expressions.minus import MinusExpression
     from vellum.workflows.expressions.not_between import NotBetweenExpression
     from vellum.workflows.expressions.not_in import NotInExpression
     from vellum.workflows.expressions.or_ import OrExpression
@@ -42,11 +47,15 @@ class BaseDescriptor(Generic[_T]):
     _name: str
     _types: Tuple[Type[_T], ...]
     _instance: Optional[_T]
+    _is_sensitive: bool = False
 
-    def __init__(self, *, name: str, types: Tuple[Type[_T], ...], instance: Optional[_T] = None) -> None:
+    def __init__(
+        self, *, name: str, types: Tuple[Type[_T], ...], instance: Optional[_T] = None, is_sensitive: bool = False
+    ) -> None:
         self._name = name
         self._types = types
         self._instance = instance
+        self._is_sensitive = is_sensitive
 
     @property
     def name(self) -> str:
@@ -63,6 +72,10 @@ class BaseDescriptor(Generic[_T]):
     def resolve(self, state: "BaseState") -> _T:
         raise NotImplementedError("Descriptor must implement resolve method")
 
+    @property
+    def is_sensitive(self) -> bool:
+        return self._is_sensitive
+
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, type(self)):
             return False
@@ -125,11 +138,14 @@ class BaseDescriptor(Generic[_T]):
 
         return CoalesceExpression(lhs=self, rhs=other)
 
-    def __getitem__(self, field: Union[str, int]) -> "AccessorExpression":
+    def __getitem__(self, field: Union[str, int, "BaseDescriptor[str]", "BaseDescriptor[int]"]) -> "AccessorExpression":
         from vellum.workflows.expressions.accessor import AccessorExpression
 
         return AccessorExpression(base=self, field=field)
 
+    def __iter__(self) -> None:
+        raise TypeError(f"'{type(self).__name__}' object is not iterable")
+
     @overload
     def equals(self, other: "BaseDescriptor[_O]") -> "EqualsExpression[_T, _O]": ...
 
@@ -358,3 +374,68 @@ class BaseDescriptor(Generic[_T]):
         from vellum.workflows.expressions.parse_json import ParseJsonExpression
 
         return ParseJsonExpression(expression=self)
+
+    def is_error(self) -> "IsErrorExpression":
+        from vellum.workflows.expressions.is_error import IsErrorExpression
+
+        return IsErrorExpression(expression=self)
+
+    @overload
+    def concat(self, other: "BaseDescriptor[_O]") -> "ConcatExpression[_T, _O]": ...
+
+    @overload
+    def concat(self, other: _O) -> "ConcatExpression[_T, _O]": ...
+
+    def concat(self, other: "Union[BaseDescriptor[_O], _O]") -> "ConcatExpression[_T, _O]":
+        from vellum.workflows.expressions.concat import ConcatExpression
+
+        return ConcatExpression(lhs=self, rhs=other)
+
+    def length(self) -> "LengthExpression[_T]":
+        from vellum.workflows.expressions.length import LengthExpression
+
+        return LengthExpression(expression=self)
+
+    @overload
+    def add(self, other: "BaseDescriptor[_O]") -> "AddExpression[_T, _O]": ...
+
+    @overload
+    def add(self, other: _O) -> "AddExpression[_T, _O]": ...
+
+    def add(self, other: "Union[BaseDescriptor[_O], _O]") -> "AddExpression[_T, _O]":
+        from vellum.workflows.expressions.add import AddExpression
+
+        return AddExpression(lhs=self, rhs=other)
+
+    @overload
+    def __add__(self, other: "BaseDescriptor[_O]") -> "AddExpression[_T, _O]": ...
+
+    @overload
+    def __add__(self, other: _O) -> "AddExpression[_T, _O]": ...
+
+    def __add__(self, other: "Union[BaseDescriptor[_O], _O]") -> "AddExpression[_T, _O]":
+        from vellum.workflows.expressions.add import AddExpression
+
+        return AddExpression(lhs=self, rhs=other)
+
+    @overload
+    def minus(self, other: "BaseDescriptor[_O]") -> "MinusExpression[_T, _O]": ...
+
+    @overload
+    def minus(self, other: _O) -> "MinusExpression[_T, _O]": ...
+
+    def minus(self, other: "Union[BaseDescriptor[_O], _O]") -> "MinusExpression[_T, _O]":
+        from vellum.workflows.expressions.minus import MinusExpression
+
+        return MinusExpression(lhs=self, rhs=other)
+
+    @overload
+    def __sub__(self, other: "BaseDescriptor[_O]") -> "MinusExpression[_T, _O]": ...
+
+    @overload
+    def __sub__(self, other: _O) -> "MinusExpression[_T, _O]": ...
+
+    def __sub__(self, other: "Union[BaseDescriptor[_O], _O]") -> "MinusExpression[_T, _O]":
+        from vellum.workflows.expressions.minus import MinusExpression
+
+        return MinusExpression(lhs=self, rhs=other)

vellum/workflows/descriptors/exceptions.py

@@ -1,2 +1,19 @@
+from vellum.workflows.errors import WorkflowError, WorkflowErrorCode
+
+
 class InvalidExpressionException(Exception):
-    pass
+    def __init__(self, message: str, code: WorkflowErrorCode = WorkflowErrorCode.NODE_EXECUTION):
+        self.message = message
+        self.code = code
+        super().__init__(message)
+
+    @property
+    def error(self) -> WorkflowError:
+        return WorkflowError(
+            message=self.message,
+            code=self.code,
+        )
+
+    @staticmethod
+    def of(workflow_error: WorkflowError) -> "InvalidExpressionException":
+        return InvalidExpressionException(message=workflow_error.message, code=workflow_error.code)

vellum/workflows/descriptors/tests/test_utils.py

@@ -1,9 +1,13 @@
 import pytest
+from typing import Any, Dict
 
+from vellum.client.types.vellum_error import VellumError
 from vellum.workflows.descriptors.utils import resolve_value
 from vellum.workflows.errors.types import WorkflowError, WorkflowErrorCode
+from vellum.workflows.exceptions import NodeException
 from vellum.workflows.nodes.bases.base import BaseNode
 from vellum.workflows.references.constant import ConstantValueReference
+from vellum.workflows.references.node import NodeReference
 from vellum.workflows.state.base import BaseState
 
 
@@ -96,6 +100,27 @@ class DummyNode(BaseNode[FixtureState]):
             ).does_not_contain("test"),
             False,
         ),
+        (
+            ConstantValueReference(
+                WorkflowError(
+                    message="This is a test",
+                    code=WorkflowErrorCode.USER_DEFINED_ERROR,
+                )
+            ).is_error(),
+            True,
+        ),
+        (
+            ConstantValueReference(
+                VellumError(
+                    message="This is a test",
+                    code="USER_DEFINED_ERROR",
+                )
+            ).is_error(),
+            True,
+        ),
+        (FixtureState.alpha.is_error(), False),
+        (FixtureState.eta.is_error(), False),
+        (DummyNode.Outputs.empty.is_error(), False),
         (ConstantValueReference('{"foo": "bar"}').parse_json(), {"foo": "bar"}),
         (ConstantValueReference('{"foo": "bar"}').parse_json()["foo"], "bar"),
         (ConstantValueReference("[1, 2, 3]").parse_json(), [1, 2, 3]),
@@ -103,6 +128,10 @@ class DummyNode(BaseNode[FixtureState]):
         (ConstantValueReference(b'{"foo": "bar"}').parse_json(), {"foo": "bar"}),
         (ConstantValueReference(bytearray(b'{"foo": "bar"}')).parse_json(), {"foo": "bar"}),
         (ConstantValueReference(b'{"key": "\xf0\x9f\x8c\x9f"}').parse_json(), {"key": "🌟"}),
+        # Test + operator
+        (FixtureState.alpha + FixtureState.beta, 3),
+        (FixtureState.gamma + FixtureState.delta, "helloel"),
+        (FixtureState.theta + FixtureState.theta, ["baz", "baz"]),
     ],
     ids=[
         "or",
@@ -150,6 +179,11 @@ class DummyNode(BaseNode[FixtureState]):
         "list_index",
         "error_contains",
         "error_does_not_contain",
+        "is_error_on_workflow_error",
+        "is_error_on_vellum_error",
+        "is_error_on_value",
+        "is_error_on_null",
+        "is_error_on_undefined",
         "parse_json_constant",
         "parse_json_accessor",
         "parse_json_list",
@@ -157,8 +191,31 @@ class DummyNode(BaseNode[FixtureState]):
         "parse_json_bytes",
         "parse_json_bytearray",
         "parse_json_bytes_with_utf8_chars",
+        "add_integers",
+        "add_strings",
+        "add_lists",
     ],
 )
 def test_resolve_value__happy_path(descriptor, expected_value):
     actual_value = resolve_value(descriptor, FixtureState())
     assert actual_value == expected_value
+
+
+def test_resolve_value__node_reference_without_is_sensitive__raises_node_exception():
+    """
+    Tests that resolve_value handles NodeReference (which bypasses BaseDescriptor.__init__) gracefully.
+    """
+
+    # GIVEN a NodeReference that doesn't have _is_sensitive defined
+    node_ref = NodeReference(name="test_node", types=(str,), node_class=DummyNode)
+
+    # AND a state object
+    state = FixtureState()
+
+    # AND a memo dict to track resolved values (important-comment)
+    memo: Dict[str, Any] = {}
+
+    # WHEN we call resolve_value with this NodeReference (important-comment)
+    # THEN it should raise NodeException (not AttributeError)
+    with pytest.raises(NodeException, match="NodeDescriptors cannot be resolved during runtime"):
+        resolve_value(node_ref, state, path="test.path", memo=memo)

vellum/workflows/descriptors/utils.py

@@ -1,7 +1,8 @@
 from collections.abc import Mapping
 import dataclasses
 import inspect
-from typing import Any, Dict, Optional, Sequence, Set, TypeVar, Union, cast, overload
+from typing import Any, Dict, Optional, Sequence, Set, Type, TypeVar, Union, cast, overload
+from typing_extensions import TypeGuard
 
 from pydantic import BaseModel
 
@@ -32,13 +33,19 @@ def resolve_value(
     from the `_T` generic.
     """
 
+    if memo is not None and path in memo:
+        return cast(_T, memo[path])
+
     if inspect.isclass(value):
         return cast(_T, value)
 
     if isinstance(value, BaseDescriptor):
         resolved_value = value.resolve(state)
         if memo is not None:
-            memo[path] = resolved_value
+            if value.is_sensitive:
+                memo[path] = value
+            else:
+                memo[path] = resolved_value
         return resolved_value
 
     if isinstance(value, property) or callable(value):
@@ -103,7 +110,7 @@ def is_unresolved(value: Any) -> bool:
         return any(is_unresolved(getattr(value, field.name)) for field in dataclasses.fields(value))
 
     if isinstance(value, BaseModel):
-        return any(is_unresolved(getattr(value, key)) for key in value.model_fields.keys())
+        return any(is_unresolved(getattr(value, key)) for key in value.__class__.model_fields.keys())
 
     if isinstance(value, Mapping):
         return any(is_unresolved(item) for item in value.values())
@@ -115,3 +122,20 @@ def is_unresolved(value: Any) -> bool:
         return any(is_unresolved(item) for item in value)
 
     return False
+
+
+_ResolvedType = TypeVar("_ResolvedType")
+
+
+def is_resolved_instance(value: Any, type_: Type[_ResolvedType]) -> TypeGuard[_ResolvedType]:
+    """
+    Checks if a value is an instance of a type or a descriptor that resolves to that type.
+    """
+
+    if isinstance(value, type_):
+        return True
+
+    if isinstance(value, BaseDescriptor) and value.types:
+        return issubclass(value.types[0], type_)
+
+    return False

vellum/workflows/edges/__init__.py

@@ -1,5 +1,7 @@
 from .edge import Edge
+from .trigger_edge import TriggerEdge
 
 __all__ = [
     "Edge",
+    "TriggerEdge",
 ]

vellum/workflows/edges/trigger_edge.py

@@ -0,0 +1,67 @@
+from typing import TYPE_CHECKING, Any, Type
+
+if TYPE_CHECKING:
+    from vellum.workflows.nodes.bases import BaseNode
+    from vellum.workflows.triggers.base import BaseTrigger
+
+
+class TriggerEdge:
+    """
+    Represents an edge from a Trigger to a Node in the workflow graph.
+
+    TriggerEdge is analogous to Edge, but connects triggers to nodes instead of
+    nodes to nodes. These edges define which nodes should be executed when a
+    particular trigger fires.
+
+    Examples:
+        ManualTrigger >> MyNode  # Creates TriggerEdge(ManualTrigger, MyNode)
+        SlackTrigger >> ProcessNode  # Creates TriggerEdge(SlackTrigger, ProcessNode)
+
+    Attributes:
+        trigger_class: The trigger class that initiates execution
+        to_node: The node that should execute when the trigger fires
+    """
+
+    def __init__(self, trigger_class: Type["BaseTrigger"], to_node: Type["BaseNode"]):
+        """
+        Initialize a TriggerEdge.
+
+        Args:
+            trigger_class: The trigger class that initiates execution
+            to_node: The node class that should execute when triggered
+        """
+        self.trigger_class = trigger_class
+        self.to_node = to_node
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Two TriggerEdges are equal if they have the same trigger and target node.
+
+        Args:
+            other: Another object to compare with
+
+        Returns:
+            True if both edges connect the same trigger to the same node
+        """
+        if not isinstance(other, TriggerEdge):
+            return False
+
+        return self.trigger_class == other.trigger_class and self.to_node == other.to_node
+
+    def __hash__(self) -> int:
+        """
+        Hash based on trigger and target node for set/dict operations.
+
+        Returns:
+            Hash value for this edge
+        """
+        return hash((self.trigger_class, self.to_node))
+
+    def __repr__(self) -> str:
+        """
+        String representation showing the trigger-to-node connection.
+
+        Returns:
+            String in format "TriggerName >> NodeName"
+        """
+        return f"{self.trigger_class.__name__} >> {self.to_node.__name__}"

vellum/workflows/emitters/__init__.py

@@ -1,5 +1,7 @@
 from .base import BaseWorkflowEmitter
+from .vellum_emitter import VellumEmitter
 
 __all__ = [
     "BaseWorkflowEmitter",
+    "VellumEmitter",
 ]

vellum/workflows/emitters/base.py

@@ -1,10 +1,27 @@
 from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Optional
 
 from vellum.workflows.events.workflow import WorkflowEvent
 from vellum.workflows.state.base import BaseState
 
+# To protect against circular imports
+if TYPE_CHECKING:
+    from vellum.workflows.state.context import WorkflowContext
+
 
 class BaseWorkflowEmitter(ABC):
+    def __init__(self):
+        self._context: Optional["WorkflowContext"] = None
+
+    def register_context(self, context: "WorkflowContext") -> None:
+        """
+        Register the workflow context with this emitter.
+
+        Args:
+            context: The workflow context containing shared resources like vellum_client.
+        """
+        self._context = context
+
     @abstractmethod
     def emit_event(self, event: WorkflowEvent) -> None:
         pass
@@ -12,3 +29,11 @@ class BaseWorkflowEmitter(ABC):
     @abstractmethod
     def snapshot_state(self, state: BaseState) -> None:
         pass
+
+    @abstractmethod
+    def join(self) -> None:
+        """
+        Wait for any background threads or timers used by this emitter to complete.
+        This ensures all pending work is finished before the workflow terminates.
+        """
+        pass

vellum/workflows/emitters/vellum_emitter.py

@@ -0,0 +1,150 @@
+import logging
+import threading
+from typing import List, Optional
+
+from vellum.core.request_options import RequestOptions
+from vellum.workflows.emitters.base import BaseWorkflowEmitter
+from vellum.workflows.events.workflow import WorkflowEvent as SDKWorkflowEvent
+from vellum.workflows.state.base import BaseState
+
+logger = logging.getLogger(__name__)
+
+DISALLOWED_EVENTS = {"workflow.execution.streaming", "node.execution.streaming"}
+
+
+class VellumEmitter(BaseWorkflowEmitter):
+    """
+    Emitter that sends workflow events to Vellum's infrastructure for monitoring
+    externally hosted SDK-powered workflows.
+
+    Usage:
+        class MyWorkflow(BaseWorkflow):
+            emitters = [VellumEmitter]
+
+    The emitter will automatically use the same Vellum client configuration
+    as the workflow it's attached to.
+    """
+
+    def __init__(
+        self,
+        *,
+        timeout: Optional[float] = 30.0,
+        max_retries: int = 3,
+        debounce_timeout: float = 0.1,
+    ):
+        """
+        Initialize the VellumEmitter.
+
+        Args:
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retry attempts for failed requests.
+            debounce_timeout: Time in seconds to wait before sending batched events.
+        """
+        super().__init__()
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._debounce_timeout = debounce_timeout
+        self._event_queue: List[SDKWorkflowEvent] = []
+        self._queue_lock = threading.Lock()
+        self._debounce_timer: Optional[threading.Timer] = None
+
+    def emit_event(self, event: SDKWorkflowEvent) -> None:
+        """
+        Queue a workflow event for batched emission to Vellum's infrastructure.
+
+        Args:
+            event: The workflow event to emit.
+        """
+        if not self._context:
+            return
+
+        if event.name in DISALLOWED_EVENTS:
+            return
+
+        try:
+            with self._queue_lock:
+                self._event_queue.append(event)
+
+                if self._debounce_timer:
+                    self._debounce_timer.cancel()
+
+                self._debounce_timer = threading.Timer(self._debounce_timeout, self._flush_events)
+                self._debounce_timer.start()
+
+        except Exception as e:
+            logger.exception(f"Failed to queue event {event.name}: {e}")
+
+    def _flush_events(self) -> None:
+        """
+        Send all queued events as a batch to Vellum's infrastructure.
+        """
+        with self._queue_lock:
+            if not self._event_queue:
+                return
+
+            events_to_send = self._event_queue.copy()
+            self._event_queue.clear()
+            self._debounce_timer = None
+
+        try:
+            self._send_events(events_to_send)
+        except Exception as e:
+            logger.exception(f"Failed to send batched events: {e}")
+
+    def __del__(self) -> None:
+        """
+        Cleanup: flush any pending events and cancel timer.
+        """
+        try:
+            if self._debounce_timer:
+                self._debounce_timer.cancel()
+            self._flush_events()
+        except Exception:
+            pass
+
+    def snapshot_state(self, state: BaseState) -> None:
+        """
+        Send a state snapshot to Vellum's infrastructure.
+
+        Args:
+            state: The workflow state to snapshot.
+        """
+        pass
+
+    def _send_events(self, events: List[SDKWorkflowEvent]) -> None:
+        """
+        Send events to Vellum's events endpoint using client.events.create.
+
+        Args:
+            events: List of WorkflowEvent objects to send.
+        """
+        if not self._context:
+            logger.warning("Cannot send events: No workflow context registered")
+            return
+
+        if not events:
+            return
+
+        client = self._context.vellum_client
+        if self._timeout is not None:
+            request_options = RequestOptions(timeout_in_seconds=int(self._timeout), max_retries=self._max_retries)
+        else:
+            request_options = RequestOptions(max_retries=self._max_retries)
+
+        client.events.create(
+            # The API accepts a ClientWorkflowEvent but our SDK emits an SDKWorkflowEvent. These shapes are
+            # meant to be identical, just with different helper methods. We may consolidate the two in the future.
+            # But for now, the type ignore allows us to avoid an additional Model -> json -> Model conversion.
+            request=events,  # type: ignore[arg-type]
+            request_options=request_options,
+        )
+
+    def join(self) -> None:
+        """
+        Wait for any background threads or timers used by this emitter to complete.
+        This ensures all pending work is finished before the workflow terminates.
+        """
+        self._flush_events()
+
+        if self._debounce_timer and self._debounce_timer.is_alive():
+            self._debounce_timer.join()

vellum/workflows/environment/__init__.py

@@ -1,5 +1,6 @@
-from .environment import Environment
+from .environment import Environment, EnvironmentVariables
 
 __all__ = [
+    "EnvironmentVariables",
     "Environment",
 ]

vellum/workflows/environment/environment.py

@@ -3,7 +3,14 @@ from typing import Optional
 from vellum.workflows.references import EnvironmentVariableReference
 
 
-class Environment:
+class EnvironmentVariables:
     @staticmethod
-    def get(name: str, default: Optional[str] = None) -> EnvironmentVariableReference:
-        return EnvironmentVariableReference(name=name, default=default)
+    def get(name: str, default: Optional[str] = None):
+        env_ref = EnvironmentVariableReference(name=name)
+        if default is not None:
+            return env_ref.coalesce(default)
+        return env_ref
+
+
+# Deprecated: Use EnvironmentVariables instead. Will be removed in v0.15.0
+Environment = EnvironmentVariables