vellum-ai 1.0.9__py3-none-any.whl → 1.0.11__py3-none-any.whl

vellum/client/core/client_wrapper.py

@@ -25,10 +25,10 @@ class BaseClientWrapper:
 
     def get_headers(self) -> typing.Dict[str, str]:
         headers: typing.Dict[str, str] = {
-            "User-Agent": "vellum-ai/1.0.9",
+            "User-Agent": "vellum-ai/1.0.11",
             "X-Fern-Language": "Python",
             "X-Fern-SDK-Name": "vellum-ai",
-            "X-Fern-SDK-Version": "1.0.9",
+            "X-Fern-SDK-Version": "1.0.11",
         }
         if self._api_version is not None:
             headers["X-API-Version"] = self._api_version

vellum/workflows/descriptors/base.py

@@ -2,6 +2,7 @@ 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
@@ -26,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
@@ -127,7 +130,7 @@ 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)
@@ -376,3 +379,30 @@ class BaseDescriptor(Generic[_T]):
         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 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)

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
 
@@ -115,3 +116,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/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

vellum/workflows/emitters/vellum_emitter.py

@@ -0,0 +1,138 @@
+import logging
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from vellum.workflows.emitters.base import BaseWorkflowEmitter
+from vellum.workflows.events.types import default_serializer
+from vellum.workflows.events.workflow import WorkflowEvent
+from vellum.workflows.state.base import BaseState
+
+logger = logging.getLogger(__name__)
+
+
+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,
+    ):
+        """
+        Initialize the VellumEmitter.
+
+        Args:
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retry attempts for failed requests.
+        """
+        super().__init__()
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._events_endpoint = "events"  # TODO: make this configurable with the correct url
+
+    def emit_event(self, event: WorkflowEvent) -> None:
+        """
+        Emit a workflow event to Vellum's infrastructure.
+
+        Args:
+            event: The workflow event to emit.
+        """
+        if not self._context:
+            return
+
+        try:
+            event_data = default_serializer(event)
+
+            self._send_event(event_data)
+
+        except Exception as e:
+            logger.exception(f"Failed to emit event {event.name}: {e}")
+
+    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_event(self, event_data: Dict[str, Any]) -> None:
+        """
+        Send event data to Vellum's events endpoint with retry logic.
+
+        Args:
+            event_data: The serialized event data to send.
+        """
+        if not self._context:
+            logger.warning("Cannot send event: No workflow context registered")
+            return
+
+        client = self._context.vellum_client
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                # Use the Vellum client's underlying HTTP client to make the request
+                # For proper authentication headers and configuration
+                base_url = client._client_wrapper.get_environment().default
+                response = client._client_wrapper.httpx_client.request(
+                    method="POST",
+                    path=f"{base_url}/{self._events_endpoint}",  # TODO: will be replaced with the correct url
+                    json=event_data,
+                    headers=client._client_wrapper.get_headers(),
+                    request_options={"timeout_in_seconds": self._timeout},
+                )
+
+                response.raise_for_status()
+
+                if attempt > 0:
+                    logger.info(f"Event sent successfully after {attempt + 1} attempts")
+                return
+
+            except httpx.HTTPStatusError as e:
+                if e.response.status_code >= 500:
+                    # Server errors might be transient, retry
+                    if attempt < self._max_retries:
+                        wait_time = min(2**attempt, 60)  # Exponential backoff, max 60s
+                        logger.warning(
+                            f"Server error emitting event (attempt {attempt + 1}/{self._max_retries + 1}): "
+                            f"{e.response.status_code}. Retrying in {wait_time}s..."
+                        )
+                        time.sleep(wait_time)
+                        continue
+                    else:
+                        logger.exception(
+                            f"Server error emitting event after {self._max_retries + 1} attempts: "
+                            f"{e.response.status_code} {e.response.text}"
+                        )
+                        return
+                else:
+                    # Client errors (4xx) are not retriable
+                    logger.exception(f"Client error emitting event: {e.response.status_code} {e.response.text}")
+                    return
+
+            except httpx.RequestError as e:
+                if attempt < self._max_retries:
+                    wait_time = min(2**attempt, 60)  # Exponential backoff, max 60s
+                    logger.warning(
+                        f"Network error emitting event (attempt {attempt + 1}/{self._max_retries + 1}): "
+                        f"{e}. Retrying in {wait_time}s..."
+                    )
+                    time.sleep(wait_time)
+                    continue
+                else:
+                    logger.exception(f"Network error emitting event after {self._max_retries + 1} attempts: {e}")
+                    return

vellum/workflows/expressions/accessor.py

@@ -7,10 +7,11 @@ 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,7 +19,7 @@ class AccessorExpression(BaseDescriptor[Any]):
         self,
         *,
         base: BaseDescriptor[LHS],
-        field: Union[str, int],
+        field: AccessorField,
     ) -> None:
         super().__init__(
             name=f"{base.name}.{field}",
@@ -28,7 +29,7 @@ class AccessorExpression(BaseDescriptor[Any]):
         self._base = base
         self._field = field
 
-    def _infer_accessor_types(self, base: BaseDescriptor[LHS], field: Union[str, int]) -> tuple[Type, ...]:
+    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.
@@ -42,7 +43,7 @@ class AccessorExpression(BaseDescriptor[Any]):
             origin = get_origin(base_type)
             args = get_args(base_type)
 
-            if isinstance(field, int) and origin in (list, tuple) and args:
+            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 ...:
@@ -52,44 +53,51 @@ class AccessorExpression(BaseDescriptor[Any]):
                         inferred_types.append(args[field])
                     else:
                         inferred_types.append(args[field])
-            elif isinstance(field, str) and origin in (dict,) and len(args) >= 2:
+            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")
 
             try:
-                return getattr(base, self._field)
+                return getattr(base, accessor_field)
             except AttributeError:
-                raise InvalidExpressionException(f"Field '{self._field}' not found on dataclass {type(base).__name__}")
+                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")
 
             try:
-                return getattr(base, self._field)
+                return getattr(base, accessor_field)
             except AttributeError:
-                raise InvalidExpressionException(f"Field '{self._field}' not found on BaseModel {type(base).__name__}")
+                raise InvalidExpressionException(
+                    f"Field '{accessor_field}' not found on BaseModel {type(base).__name__}"
+                )
 
         if isinstance(base, Mapping):
             try:
-                return base[self._field]
+                return base[accessor_field]
             except KeyError:
-                raise InvalidExpressionException(f"Key '{self._field}' not found in mapping")
+                raise InvalidExpressionException(f"Key '{accessor_field}' not found in mapping")
 
         if isinstance(base, Sequence):
             try:
-                index = int(self._field)
+                index = int(accessor_field)
                 return base[index]
             except (IndexError, ValueError):
-                if isinstance(self._field, int) or (isinstance(self._field, str) and self._field.lstrip("-").isdigit()):
+                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)}"
                     )

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/length.py

@@ -0,0 +1,35 @@
+from typing import Generic, TypeVar, Union
+
+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
+
+_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 hasattr(expression, "__len__"):
+            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)}")

vellum/workflows/expressions/minus.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 SupportsMinus(Protocol):
+    def __sub__(self, other: Any) -> Any: ...
+
+
+def has_sub(obj: Any) -> TypeGuard[SupportsMinus]:
+    return hasattr(obj, "__sub__")
+
+
+LHS = TypeVar("LHS")
+RHS = TypeVar("RHS")
+
+
+class MinusExpression(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_sub(lhs):
+            raise InvalidExpressionException(f"'{lhs.__class__.__name__}' must support the '-' operator")
+
+        return lhs - rhs

vellum/workflows/expressions/tests/test_add.py

@@ -0,0 +1,72 @@
+import pytest
+
+from vellum.workflows.descriptors.exceptions import InvalidExpressionException
+from vellum.workflows.expressions.add import AddExpression
+from vellum.workflows.state.base import BaseState
+
+
+class TestState(BaseState):
+    number_value: int = 5
+    string_value: str = "hello"
+
+
+def test_add_expression_numbers():
+    """
+    Tests that AddExpression correctly adds two numbers.
+    """
+
+    state = TestState()
+
+    expression = TestState.number_value.add(10)
+
+    result = expression.resolve(state)
+    assert result == 15
+
+
+def test_add_expression_strings():
+    """
+    Tests that AddExpression correctly concatenates two strings.
+    """
+
+    state = TestState()
+
+    expression = TestState.string_value.add(" world")
+
+    result = expression.resolve(state)
+    assert result == "hello world"
+
+
+def test_add_expression_unsupported_type():
+    """
+    Tests that AddExpression raises an exception for unsupported types.
+    """
+
+    class NoAddSupport:
+        pass
+
+    no_add_obj = NoAddSupport()
+    expression = AddExpression(lhs=no_add_obj, rhs=5)
+    state = TestState()
+
+    with pytest.raises(InvalidExpressionException, match="'NoAddSupport' must support the '\\+' operator"):
+        expression.resolve(state)
+
+
+def test_add_expression_name():
+    """
+    Tests that AddExpression has the correct name.
+    """
+
+    expression = AddExpression(lhs=5, rhs=3)
+
+    assert expression.name == "5 + 3"
+
+
+def test_add_expression_types():
+    """
+    Tests that AddExpression has the correct types.
+    """
+
+    expression = AddExpression(lhs=5, rhs=3)
+
+    assert expression.types == (object,)

vellum/workflows/expressions/tests/test_length.py

@@ -0,0 +1,38 @@
+import pytest
+
+from vellum.workflows.constants import undefined
+from vellum.workflows.descriptors.exceptions import InvalidExpressionException
+from vellum.workflows.expressions.length import LengthExpression
+from vellum.workflows.state.base import BaseState
+
+
+class TestState(BaseState):
+    string_value: str = "hello world"
+
+
+def test_length_expression_string():
+    """
+    Tests that LengthExpression correctly returns the length of a string.
+    """
+
+    state = TestState()
+
+    expression = TestState.string_value.length()
+    result = expression.resolve(state)
+
+    assert result == 11
+
+
+def test_length_expression_undefined():
+    """
+    Tests that LengthExpression raises an exception for undefined values.
+    """
+
+    expression = LengthExpression(expression=undefined)
+    state = TestState()
+
+    # THEN we should get an InvalidExpressionException
+    with pytest.raises(InvalidExpressionException) as exc_info:
+        expression.resolve(state)
+
+    assert "Cannot get length of undefined value" in str(exc_info.value)

vellum/workflows/expressions/tests/test_minus.py

@@ -0,0 +1,72 @@
+import pytest
+
+from vellum.workflows.descriptors.exceptions import InvalidExpressionException
+from vellum.workflows.expressions.minus import MinusExpression
+from vellum.workflows.state.base import BaseState
+
+
+class TestState(BaseState):
+    number_value: int = 10
+    float_value: float = 15.5
+
+
+def test_minus_expression_numbers():
+    """
+    Tests that MinusExpression correctly subtracts two numbers.
+    """
+
+    state = TestState()
+
+    expression = TestState.number_value.minus(3)
+
+    result = expression.resolve(state)
+    assert result == 7
+
+
+def test_minus_expression_floats():
+    """
+    Tests that MinusExpression correctly subtracts two floats.
+    """
+
+    state = TestState()
+
+    expression = TestState.float_value.minus(5.5)
+
+    result = expression.resolve(state)
+    assert result == 10.0
+
+
+def test_minus_expression_unsupported_type():
+    """
+    Tests that MinusExpression raises an exception for unsupported types.
+    """
+
+    class NoSubSupport:
+        pass
+
+    no_sub_obj = NoSubSupport()
+    expression = MinusExpression(lhs=no_sub_obj, rhs=5)
+    state = TestState()
+
+    with pytest.raises(InvalidExpressionException, match="'NoSubSupport' must support the '-' operator"):
+        expression.resolve(state)
+
+
+def test_minus_expression_name():
+    """
+    Tests that MinusExpression has the correct name.
+    """
+
+    expression = MinusExpression(lhs=10, rhs=3)
+
+    assert expression.name == "10 - 3"
+
+
+def test_minus_expression_types():
+    """
+    Tests that MinusExpression has the correct types.
+    """
+
+    expression = MinusExpression(lhs=10, rhs=3)
+
+    assert expression.types == (object,)