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

vellum/workflows/references/state_value.py

@@ -1,8 +1,11 @@
-from typing import TYPE_CHECKING, TypeVar, cast
+from functools import cached_property
+from uuid import UUID
+from typing import TYPE_CHECKING, Optional, Tuple, Type, TypeVar, cast
 
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.errors.types import WorkflowErrorCode
 from vellum.workflows.exceptions import NodeException
+from vellum.workflows.utils.uuids import get_state_value_id
 
 if TYPE_CHECKING:
     from vellum.workflows.state.base import BaseState
@@ -13,6 +16,26 @@ _T = TypeVar("_T")
 
 class StateValueReference(BaseDescriptor[_T]):
 
+    def __init__(
+        self,
+        *,
+        name: str,
+        types: Tuple[Type[_T], ...],
+        instance: Optional[_T],
+        state_class: Type["BaseState"],
+    ) -> None:
+        super().__init__(name=name, types=types, instance=instance)
+        self._state_class = state_class
+
+    @property
+    def state_class(self) -> Type["BaseState"]:
+        return self._state_class
+
+    @cached_property
+    def id(self) -> UUID:
+        """Generate deterministic UUID from state class and state value name."""
+        return get_state_value_id(self._state_class, self.name)
+
     def resolve(self, state: "BaseState") -> _T:
         if hasattr(state, self._name):
             return cast(_T, getattr(state, self._name))

vellum/workflows/references/tests/test_lazy.py

@@ -1,9 +1,29 @@
 import pytest
 
+from vellum.workflows import BaseWorkflow
 from vellum.workflows.nodes import BaseNode
 from vellum.workflows.references.lazy import LazyReference
 
 
+class ResponseNode(BaseNode):
+    class Outputs(BaseNode.Outputs):
+        response: str = "Hello from node!"
+
+
+class TestWorkflowWithOutput(BaseWorkflow):
+    graph = ResponseNode
+
+    class Outputs(BaseWorkflow.Outputs):
+        final_response = ResponseNode.Outputs.response
+
+
+class TestWorkflowWithLiteralOutput(BaseWorkflow):
+    graph = ResponseNode
+
+    class Outputs(BaseWorkflow.Outputs):
+        literal_value = "Hello literal!"
+
+
 @pytest.fixture
 def mock_inspect_getsource(mocker):
     return mocker.patch("inspect.getsource")
@@ -28,3 +48,41 @@ def test_lazy_reference__inspect_getsource_fails(mock_inspect_getsource, mock_lo
 
     # AND sentry is notified
     assert mock_logger.exception.call_count == 1
+
+
+def test_lazy_reference__string_resolves_workflow_output():
+    """Tests that string-based LazyReference can resolve workflow output references."""
+
+    # GIVEN a workflow with an output that references a node output (defined at module level)
+    # WHEN we run the workflow
+    terminal_event = TestWorkflowWithOutput().run()
+
+    # THEN the workflow completes successfully
+    assert terminal_event.name == "workflow.execution.fulfilled"
+    assert terminal_event.final_state is not None
+
+    # AND we can resolve a string-based LazyReference to the workflow output
+    lazy_ref = LazyReference[str]("TestWorkflowWithOutput.Outputs.final_response")
+    resolved_value = lazy_ref.resolve(terminal_event.final_state)
+
+    # THEN the resolved value matches the node output
+    assert resolved_value == "Hello from node!"
+
+
+def test_lazy_reference__string_resolves_literal_workflow_output():
+    """Tests that string-based LazyReference can resolve literal workflow output values."""
+
+    # GIVEN a workflow with a literal output value (defined at module level)
+    # WHEN we run the workflow
+    terminal_event = TestWorkflowWithLiteralOutput().run()
+
+    # THEN the workflow completes successfully
+    assert terminal_event.name == "workflow.execution.fulfilled"
+    assert terminal_event.final_state is not None
+
+    # AND we can resolve a string-based LazyReference to the literal workflow output
+    lazy_ref = LazyReference[str]("TestWorkflowWithLiteralOutput.Outputs.literal_value")
+    resolved_value = lazy_ref.resolve(terminal_event.final_state)
+
+    # THEN the resolved value matches the literal output
+    assert resolved_value == "Hello literal!"

vellum/workflows/references/trigger.py

@@ -0,0 +1,82 @@
+"""Descriptor for referring to trigger attributes in workflow graphs."""
+
+from __future__ import annotations
+
+from uuid import UUID
+from typing import TYPE_CHECKING, Any, Generic, Optional, Tuple, Type, TypeVar, cast
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+from vellum.workflows.descriptors.base import BaseDescriptor
+from vellum.workflows.errors.types import WorkflowErrorCode
+from vellum.workflows.exceptions import NodeException
+
+if TYPE_CHECKING:
+    from vellum.workflows.state.base import BaseState
+    from vellum.workflows.triggers.base import BaseTrigger
+
+_T = TypeVar("_T")
+
+
+class TriggerAttributeReference(BaseDescriptor[_T], Generic[_T]):
+    """Reference to a trigger attribute defined via type annotations."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        types: Tuple[Type[_T], ...],
+        instance: Optional[_T],
+        trigger_class: Type[BaseTrigger],
+    ) -> None:
+        super().__init__(name=name, types=types, instance=instance)
+        self._trigger_class = trigger_class
+
+    @property
+    def trigger_class(self) -> Type[BaseTrigger]:
+        return self._trigger_class
+
+    @property
+    def id(self) -> UUID:
+        """
+        Get the trigger attribute ID via the trigger class, which knows how to read
+        metadata.json and fall back to hash-based IDs.
+
+        This ensures trigger attribute IDs remain stable across serialization round-trips
+        when metadata.json is present.
+        """
+        return self._trigger_class.get_attribute_id(self.name)
+
+    def resolve(self, state: BaseState) -> _T:
+        trigger_attributes = getattr(state.meta, "trigger_attributes", {})
+        if self in trigger_attributes:
+            return cast(_T, trigger_attributes[self])
+
+        if state.meta.parent:
+            return self.resolve(state.meta.parent)
+
+        if type(None) in self.types:
+            return cast(_T, None)
+
+        raise NodeException(
+            message=f"Missing trigger attribute '{self.name}' for {self._trigger_class.__name__}",
+            code=WorkflowErrorCode.INVALID_INPUTS,
+        )
+
+    def __repr__(self) -> str:
+        return f"{self._trigger_class.__qualname__}.{self.name}"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, TriggerAttributeReference):
+            return False
+        return super().__eq__(other) and self._trigger_class == other._trigger_class
+
+    def __hash__(self) -> int:
+        return hash((self._trigger_class, self._name))
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Type[Any], handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        return core_schema.is_instance_schema(cls)

vellum/workflows/references/workflow_input.py

@@ -1,9 +1,12 @@
+from functools import cached_property
+from uuid import UUID
 from typing import TYPE_CHECKING, Generic, Optional, Tuple, Type, TypeVar, cast
 
 from vellum.workflows.descriptors.base import BaseDescriptor
 from vellum.workflows.errors.types import WorkflowErrorCode
 from vellum.workflows.exceptions import NodeException
 from vellum.workflows.types.generics import import_workflow_class
+from vellum.workflows.utils.uuids import get_workflow_input_id
 
 if TYPE_CHECKING:
     from vellum.workflows.inputs.base import BaseInputs
@@ -29,6 +32,11 @@ class WorkflowInputReference(BaseDescriptor[_InputType], Generic[_InputType]):
     def inputs_class(self) -> Type["BaseInputs"]:
         return self._inputs_class
 
+    @cached_property
+    def id(self) -> UUID:
+        """Generate deterministic UUID from inputs class and input name."""
+        return get_workflow_input_id(self._inputs_class, self.name)
+
     def resolve(self, state: "BaseState") -> _InputType:
         if hasattr(state.meta.workflow_inputs, self._name) and (
             state.meta.workflow_definition == self._inputs_class.__parent_class__

vellum/workflows/resolvers/base.py

@@ -1,11 +1,25 @@
 from abc import ABC, abstractmethod
-from typing import Iterator
+from uuid import UUID
+from typing import TYPE_CHECKING, Iterator, Optional, Type, Union
 
 from vellum.workflows.events.workflow import WorkflowEvent
+from vellum.workflows.resolvers.types import LoadStateResult
 from vellum.workflows.state.base import BaseState
 
+if TYPE_CHECKING:
+    from vellum.workflows.state.context import WorkflowContext
+    from vellum.workflows.workflows.base import BaseWorkflow
+
 
 class BaseWorkflowResolver(ABC):
+    def __init__(self):
+        self._context: Optional["WorkflowContext"] = None
+        self._workflow_class: Optional[Type["BaseWorkflow"]] = None
+
+    def register_workflow_instance(self, workflow_instance: "BaseWorkflow") -> None:
+        self._workflow_class = type(workflow_instance)
+        self._context = workflow_instance.context
+
     @abstractmethod
     def get_latest_execution_events(self) -> Iterator[WorkflowEvent]:
         pass
@@ -13,3 +27,7 @@ class BaseWorkflowResolver(ABC):
     @abstractmethod
     def get_state_snapshot_history(self) -> Iterator[BaseState]:
         pass
+
+    @abstractmethod
+    def load_state(self, previous_execution_id: Optional[Union[UUID, str]] = None) -> Optional[LoadStateResult]:
+        pass

vellum/workflows/resolvers/resolver.py

@@ -0,0 +1,81 @@
+import logging
+from uuid import UUID
+from typing import Iterator, Optional, Type, Union
+
+from vellum.client.core.api_error import ApiError
+from vellum.workflows.events.workflow import WorkflowEvent
+from vellum.workflows.nodes.utils import cast_to_output_type
+from vellum.workflows.resolvers.base import BaseWorkflowResolver
+from vellum.workflows.resolvers.types import LoadStateResult
+from vellum.workflows.state.base import BaseState
+
+logger = logging.getLogger(__name__)
+
+
+class VellumResolver(BaseWorkflowResolver):
+    def get_latest_execution_events(self) -> Iterator[WorkflowEvent]:
+        return iter([])
+
+    def get_state_snapshot_history(self) -> Iterator[BaseState]:
+        return iter([])
+
+    def _deserialize_state(self, state_data: dict, state_class: Type[BaseState]) -> BaseState:
+        """Deserialize state data with proper type conversion for complex types like List[ChatMessage]."""
+        converted_data = {}
+
+        annotations = getattr(state_class, "__annotations__", {})
+
+        for field_name, field_value in state_data.items():
+            if field_name in annotations:
+                field_type = annotations[field_name]
+                converted_data[field_name] = cast_to_output_type(field_value, field_type)
+            else:
+                converted_data[field_name] = field_value
+
+        return state_class(**converted_data)
+
+    def load_state(self, previous_execution_id: Optional[Union[UUID, str]] = None) -> Optional[LoadStateResult]:
+        if isinstance(previous_execution_id, UUID):
+            previous_execution_id = str(previous_execution_id)
+
+        if previous_execution_id is None:
+            return None
+
+        if not self._context:
+            logger.warning("Cannot load state: No workflow context registered")
+            return None
+
+        client = self._context.vellum_client
+        try:
+            response = client.workflows.retrieve_state(
+                span_id=previous_execution_id,
+            )
+        except ApiError as e:
+            if e.status_code == 404:
+                logger.debug(
+                    "No state found for previous execution %s, continuing without previous state",
+                    previous_execution_id,
+                )
+                return None
+            raise
+
+        if response.state is None:
+            return None
+
+        if "meta" in response.state:
+            response.state.pop("meta")
+
+        if self._workflow_class:
+            state_class = self._workflow_class.get_state_class()
+            state = self._deserialize_state(response.state, state_class)
+        else:
+            logger.warning("No workflow class registered, falling back to BaseState")
+            state = BaseState(**response.state)
+
+        return LoadStateResult(
+            state=state,
+            previous_trace_id=response.trace_id,
+            previous_span_id=response.span_id,
+            root_trace_id=response.root_trace_id or response.trace_id,
+            root_span_id=response.root_span_id or response.span_id,
+        )

vellum/workflows/resolvers/tests/test_resolver.py

@@ -0,0 +1,199 @@
+from datetime import datetime
+from unittest.mock import Mock
+from uuid import uuid4
+from typing import List
+
+from vellum import ChatMessage
+from vellum.client.core.api_error import ApiError
+from vellum.client.types.workflow_resolved_state import WorkflowResolvedState
+from vellum.workflows import BaseWorkflow
+from vellum.workflows.inputs.base import BaseInputs
+from vellum.workflows.resolvers.resolver import VellumResolver
+from vellum.workflows.resolvers.types import LoadStateResult
+from vellum.workflows.state.base import BaseState, NodeExecutionCache
+from vellum.workflows.state.context import WorkflowContext
+
+
+def test_load_state_with_context_success():
+    """Test load_state successfully loads state when context and client are available."""
+    resolver = VellumResolver()
+    execution_id = uuid4()
+
+    class TestState(BaseState):
+        test_key: str = "test_value"
+
+    class TestWorkflow(BaseWorkflow[BaseInputs, TestState]):
+        pass
+
+    # GIVEN a state dictionary that matches what the resolver expects
+    prev_id = str(uuid4())
+    prev_span_id = str(uuid4())
+    state_dict = {
+        "test_key": "test_value",
+        "meta": {
+            "workflow_definition": "MockWorkflow",
+            "id": prev_id,
+            "span_id": prev_span_id,
+            "updated_ts": datetime.now().isoformat(),
+            "workflow_inputs": BaseInputs(),
+            "external_inputs": {},
+            "node_outputs": {},
+            "node_execution_cache": NodeExecutionCache(),
+            "parent": None,
+        },
+    }
+
+    previous_trace_id = str(uuid4())
+    previous_span_id = str(uuid4())
+    trace_id = str(uuid4())
+    root_trace_id = str(uuid4())
+    root_span_id = str(uuid4())
+
+    mock_response = WorkflowResolvedState(
+        trace_id=trace_id,
+        timestamp=datetime.now(),
+        span_id=str(execution_id),
+        state=state_dict,
+        previous_trace_id=previous_trace_id,
+        previous_span_id=previous_span_id,
+        root_trace_id=root_trace_id,
+        root_span_id=root_span_id,
+    )
+
+    mock_client = Mock()
+    mock_client.workflows.retrieve_state.return_value = mock_response
+
+    # AND context with the test workflow class is set up
+    context = WorkflowContext(vellum_client=mock_client)
+    TestWorkflow(context=context, resolvers=[resolver])
+
+    # WHEN load_state is called
+    result = resolver.load_state(previous_execution_id=execution_id)
+
+    # THEN should return LoadStateResult with state and span link info
+    assert isinstance(result, LoadStateResult)
+    assert result.state is not None
+    assert isinstance(result.state, TestState)
+    assert result.state.test_key == "test_value"
+
+    # AND the new state should have different meta IDs than those provided in the loaded state_dict
+    assert str(result.state.meta.id) != prev_id
+    assert str(result.state.meta.span_id) != prev_span_id
+
+    # AND should have span link info
+    assert result.previous_trace_id == trace_id
+    assert result.previous_span_id == str(execution_id)
+    assert result.root_trace_id == root_trace_id
+    assert result.root_span_id == root_span_id
+
+    mock_client.workflows.retrieve_state.assert_called_once_with(span_id=str(execution_id))
+
+
+def test_load_state_with_chat_message_list():
+    """Test load_state successfully loads state with chat_history containing ChatMessage list."""
+    resolver = VellumResolver()
+    execution_id = uuid4()
+
+    class TestStateWithChatHistory(BaseState):
+        test_key: str = "test_value"
+        chat_history: List[ChatMessage] = []
+
+    class TestWorkflow(BaseWorkflow[BaseInputs, TestStateWithChatHistory]):
+        pass
+
+    # GIVEN a state dictionary with chat_history containing ChatMessage objects
+    prev_id = str(uuid4())
+    prev_span_id = str(uuid4())
+    state_dict = {
+        "test_key": "test_value",
+        "chat_history": [
+            {"role": "USER", "text": "Hello, how are you?"},
+            {"role": "ASSISTANT", "text": "I'm doing well, thank you!"},
+            {"role": "USER", "text": "What can you help me with?"},
+        ],
+        "meta": {
+            "workflow_definition": "MockWorkflow",
+            "id": prev_id,
+            "span_id": prev_span_id,
+            "updated_ts": datetime.now().isoformat(),
+            "workflow_inputs": BaseInputs(),
+            "external_inputs": {},
+            "node_outputs": {},
+            "node_execution_cache": NodeExecutionCache(),
+            "parent": None,
+        },
+    }
+
+    previous_trace_id = str(uuid4())
+    previous_span_id = str(uuid4())
+    root_trace_id = str(uuid4())
+    root_span_id = str(uuid4())
+
+    mock_response = WorkflowResolvedState(
+        trace_id=str(uuid4()),
+        timestamp=datetime.now(),
+        span_id=str(execution_id),
+        state=state_dict,
+        previous_trace_id=previous_trace_id,
+        previous_span_id=previous_span_id,
+        root_trace_id=root_trace_id,
+        root_span_id=root_span_id,
+    )
+
+    mock_client = Mock()
+    mock_client.workflows.retrieve_state.return_value = mock_response
+
+    # AND context with the test workflow class is set up
+    context = WorkflowContext(vellum_client=mock_client)
+    TestWorkflow(context=context, resolvers=[resolver])
+
+    # WHEN load_state is called
+    result = resolver.load_state(previous_execution_id=execution_id)
+
+    # THEN should return LoadStateResult with state containing chat_history
+    assert isinstance(result, LoadStateResult)
+    assert result.state is not None
+    assert isinstance(result.state, TestStateWithChatHistory)
+    assert result.state.test_key == "test_value"
+
+    # AND the chat_history should be properly deserialized as ChatMessage objects
+    assert len(result.state.chat_history) == 3
+    assert all(isinstance(msg, ChatMessage) for msg in result.state.chat_history)
+    assert result.state.chat_history[0].role == "USER"
+    assert result.state.chat_history[0].text == "Hello, how are you?"
+    assert result.state.chat_history[1].role == "ASSISTANT"
+    assert result.state.chat_history[1].text == "I'm doing well, thank you!"
+    assert result.state.chat_history[2].role == "USER"
+    assert result.state.chat_history[2].text == "What can you help me with?"
+
+    mock_client.workflows.retrieve_state.assert_called_once_with(span_id=str(execution_id))
+
+
+def test_load_state_returns_none_on_404():
+    """Test load_state returns None when retrieve_state returns 404 (e.g., rejected execution with no state)."""
+    resolver = VellumResolver()
+    execution_id = uuid4()
+
+    class TestState(BaseState):
+        test_key: str = "test_value"
+
+    class TestWorkflow(BaseWorkflow[BaseInputs, TestState]):
+        pass
+
+    # GIVEN a mock client that raises ApiError with 404 status
+    mock_client = Mock()
+    mock_client.workflows.retrieve_state.side_effect = ApiError(
+        status_code=404,
+        body={"detail": "No state found for the given span_id"},
+    )
+
+    # AND context with the test workflow class is set up
+    context = WorkflowContext(vellum_client=mock_client)
+    TestWorkflow(context=context, resolvers=[resolver])
+
+    # WHEN load_state is called with an execution ID that has no state
+    result = resolver.load_state(previous_execution_id=execution_id)
+
+    # THEN should return None instead of raising an exception
+    assert result is None
+    mock_client.workflows.retrieve_state.assert_called_once_with(span_id=str(execution_id))

vellum/workflows/resolvers/types.py

@@ -0,0 +1,11 @@
+from typing import NamedTuple
+
+from vellum.workflows.state.base import BaseState
+
+
+class LoadStateResult(NamedTuple):
+    state: BaseState
+    previous_trace_id: str
+    previous_span_id: str
+    root_trace_id: str
+    root_span_id: str