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

vellum/workflows/workflows/base.py

@@ -29,6 +29,7 @@ from typing import (
 
 from pydantic import ValidationError
 
+from vellum.utils.uuid import is_valid_uuid
 from vellum.workflows.edges import Edge
 from vellum.workflows.emitters.base import BaseWorkflowEmitter
 from vellum.workflows.errors import WorkflowError, WorkflowErrorCode
@@ -38,6 +39,8 @@ from vellum.workflows.events.node import (
     NodeExecutionFulfilledEvent,
     NodeExecutionInitiatedBody,
     NodeExecutionInitiatedEvent,
+    NodeExecutionLogBody,
+    NodeExecutionLogEvent,
     NodeExecutionPausedBody,
     NodeExecutionPausedEvent,
     NodeExecutionRejectedBody,
@@ -74,6 +77,7 @@ from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.nodes.mocks import MockNodeExecutionArg
 from vellum.workflows.nodes.utils import get_unadorned_node
 from vellum.workflows.outputs import BaseOutputs
+from vellum.workflows.references.trigger import TriggerAttributeReference
 from vellum.workflows.resolvers.base import BaseWorkflowResolver
 from vellum.workflows.runner import WorkflowRunner
 from vellum.workflows.runner.runner import ExternalInputsArg, RunFromNodeArg
@@ -271,8 +275,6 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         for resolver in self.resolvers:
             resolver.register_workflow_instance(self)
 
-        self.validate()
-
     @property
     def context(self) -> WorkflowContext:
         return self._context
@@ -289,12 +291,12 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
             for item in graph:
                 if isinstance(item, Graph):
                     graphs.append(item)
-                elif issubclass(item, BaseNode):
+                elif inspect.isclass(item) and issubclass(item, BaseNode):
                     graphs.append(Graph.from_node(item))
                 else:
                     raise ValueError(f"Unexpected graph type: {type(item)}")
             return graphs
-        if issubclass(graph, BaseNode):
+        if inspect.isclass(graph) and issubclass(graph, BaseNode):
             return [Graph.from_node(graph)]
         raise ValueError(f"Unexpected graph type: {type(graph)}")
 
@@ -526,6 +528,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         max_concurrency: Optional[int] = None,
         timeout: Optional[float] = None,
         trigger: Optional[BaseTrigger] = None,
+        event_max_size: Optional[int] = None,
     ) -> WorkflowEventStream:
         """
         Invoke a Workflow, yielding events as they are emitted.
@@ -576,6 +579,10 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
             The trigger instance is bound to the workflow state, making its attributes accessible to downstream nodes.
             Required for workflows that only have IntegrationTrigger; optional for workflows with both ManualTrigger
             and IntegrationTrigger.
+
+        event_max_size: Optional[int] = None
+            The maximum size in bytes for serialized events. If an event's serialized size exceeds this value,
+            the outputs will be set to an empty dict.
         """
 
         should_yield = event_filter or workflow_event_filter
@@ -593,6 +600,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
             init_execution_context=self._execution_context,
             trigger=trigger,
             execution_id=execution_id,
+            event_max_size=event_max_size,
         )
         self._current_runner = runner
         runner_stream = runner.stream()
@@ -604,15 +612,28 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
 
         return WorkflowEventGenerator(_generate_filtered_events(), runner_stream.span_id)
 
-    def validate(self) -> None:
+    @classmethod
+    def validate(cls) -> None:
         """
         Validates the Workflow, by running through our list of linter rules.
         """
-        # TODO: Implement rule that all entrypoints are non empty
-        # https://app.shortcut.com/vellum/story/4327
-        pass
 
-    def _resolve_node_ref(self, node_ref: Union[Type[BaseNode], UUID, str]) -> Type[BaseNode]:
+        cls._validate_no_self_edges()
+
+    @classmethod
+    def get_all_nodes_recursive(cls) -> Iterator[Type[BaseNode]]:
+        """
+        Returns an iterator over all nodes in the Workflow, including nodes nested in subworkflows.
+        """
+        for node in cls.get_all_nodes():
+            yield node
+            for node_ref in node:
+                attr_value = node_ref.instance
+                if inspect.isclass(attr_value) and issubclass(attr_value, BaseWorkflow):
+                    yield from attr_value.get_all_nodes_recursive()
+
+    @classmethod
+    def resolve_node_ref(cls, node_ref: Union[Type[BaseNode], UUID, str]) -> Type[BaseNode]:
         """
         Resolve a node reference (class, UUID, or string) to a node class.
 
@@ -630,18 +651,27 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
             return node_ref
 
         candidate_nodes: List[Type[BaseNode]] = []
-        for node in self.get_all_nodes():
+        for node in cls.get_all_nodes_recursive():
             candidate_nodes.append(node)
             wrapped_node = get_unadorned_node(node)
             if wrapped_node != node:
                 candidate_nodes.append(wrapped_node)
 
         if isinstance(node_ref, UUID):
+            node_uuid = node_ref
+        elif is_valid_uuid(node_ref):
+            node_uuid = UUID(node_ref)
+        else:
+            node_uuid = None
+
+        if node_uuid:
             for node in candidate_nodes:
-                if node.__id__ == node_ref:
+                if node.__id__ == node_uuid:
                     return node
-            identifier = str(node_ref)
-            raise WorkflowInitializationException(message=f"Node '{identifier}' not found in workflow")
+            raise WorkflowInitializationException(
+                message=f"Node '{node_uuid}' not found in workflow",
+                raw_data={"node_ref": str(node_uuid)},
+            )
 
         if isinstance(node_ref, str):
             try:
@@ -650,14 +680,23 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
                 node_class = getattr(module, class_name)
                 if inspect.isclass(node_class) and issubclass(node_class, BaseNode):
                     return node_class
-                raise WorkflowInitializationException(message=f"Node '{node_ref}' not found in workflow")
+                raise WorkflowInitializationException(
+                    message=f"Node '{node_ref}' not found in workflow",
+                    raw_data={"node_ref": node_ref},
+                )
             except (ValueError, ModuleNotFoundError, AttributeError):
                 for node in candidate_nodes:
                     if f"{node.__module__}.{node.__name__}" == node_ref:
                         return node
-                raise WorkflowInitializationException(message=f"Node '{node_ref}' not found in workflow")
+                raise WorkflowInitializationException(
+                    message=f"Node '{node_ref}' not found in workflow",
+                    raw_data={"node_ref": node_ref},
+                )
 
-        raise WorkflowInitializationException(message=f"Node '{node_ref}' not found in workflow")
+        raise WorkflowInitializationException(
+            message=f"Node '{node_ref}' not found in workflow",
+            raw_data={"node_ref": str(node_ref)},
+        )
 
     def run_node(
         self, node: Union[Type[BaseNode], UUID, str], *, inputs: Optional[Dict[str, Any]] = None
@@ -676,7 +715,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         Raises:
             ValueError: If the node reference cannot be resolved
         """
-        resolved_node = self._resolve_node_ref(node)
+        resolved_node = self.resolve_node_ref(node)
         runner = WorkflowRunner(self)
         span_id = uuid4()
         node_instance = resolved_node(state=self.get_default_state(), context=self._context, inputs=inputs)
@@ -717,12 +756,27 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         return self.get_inputs_class()()
 
     def get_default_state(
-        self, workflow_inputs: Optional[InputsType] = None, execution_id: Optional[UUID] = None
+        self,
+        workflow_inputs: Optional[InputsType] = None,
+        execution_id: Optional[UUID] = None,
+        *,
+        trigger_attributes: Optional[Dict[TriggerAttributeReference, Any]] = None,
     ) -> StateType:
-        meta = StateMeta(
-            parent=self._parent_state,
-            workflow_inputs=workflow_inputs or self.get_default_inputs(),
-            workflow_definition=self.__class__,
+        resolved_inputs: Optional[InputsType] = workflow_inputs
+
+        meta_payload: Dict[str, Any] = {
+            "parent": self._parent_state,
+            "workflow_definition": self.__class__,
+            "workflow_inputs": resolved_inputs,
+        }
+        if trigger_attributes is not None:
+            meta_payload["trigger_attributes"] = trigger_attributes
+
+        meta = StateMeta.model_validate(
+            meta_payload,
+            context={
+                "workflow_definition": self.__class__,
+            },
         )
 
         # Makes the uuid factory mocker work this way instead of setting in cosntructor
@@ -781,11 +835,13 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
 
         state_class = cls.get_state_class()
         if "meta" in state:
+            meta_payload = dict(state["meta"])
+            if workflow_inputs is not None:
+                meta_payload["workflow_inputs"] = workflow_inputs
+            meta_payload.setdefault("workflow_definition", cls)
+
             state["meta"] = StateMeta.model_validate(
-                {
-                    **state["meta"],
-                    "workflow_inputs": workflow_inputs,
-                },
+                meta_payload,
                 context={
                     "workflow_definition": cls,
                 },
@@ -794,7 +850,9 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         return state_class(**state)
 
     @classmethod
-    def deserialize_trigger(cls, trigger_id: Optional[UUID], inputs: dict) -> Union[InputsType, BaseTrigger]:
+    def deserialize_trigger(
+        cls, trigger_id: Optional[Union[str, UUID]], inputs: dict
+    ) -> Union[InputsType, BaseTrigger]:
         """
         Deserialize a trigger from a trigger_id and inputs dict.
 
@@ -803,8 +861,12 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
 
         Parameters
         ----------
-        trigger_id: Optional[UUID]
-            The UUID of the trigger class to instantiate. If None, returns workflow Inputs.
+        trigger_id: Optional[Union[str, UUID]]
+            The identifier of the trigger class to instantiate. Can be:
+            - None: Returns workflow Inputs
+            - UUID: Matches by trigger class __id__
+            - str (valid UUID): Matches by trigger class __id__
+            - str (non-UUID): Matches by trigger name (from __trigger_name__)
 
         inputs: dict
             The inputs to pass to the trigger or Inputs constructor.
@@ -824,18 +886,54 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
             inputs_class = cls.get_inputs_class()
             return inputs_class(**inputs)
 
+        # Determine if trigger_id is a UUID or a name string
+        resolved_trigger_id: Optional[UUID] = None
+        trigger_name: Optional[str] = None
+
+        if isinstance(trigger_id, UUID):
+            resolved_trigger_id = trigger_id
+        elif is_valid_uuid(trigger_id):
+            resolved_trigger_id = UUID(trigger_id)
+        else:
+            trigger_name = trigger_id
+
         trigger_classes = []
         for subgraph in cls.get_subgraphs():
             for trigger_class in subgraph.triggers:
-                if trigger_class.__id__ == trigger_id:
-                    return trigger_class(**inputs)
+                # Match by UUID
+                if resolved_trigger_id is not None and trigger_class.__id__ == resolved_trigger_id:
+                    try:
+                        return trigger_class(**inputs)
+                    except Exception as e:
+                        raise WorkflowInitializationException(
+                            message=f"Failed to instantiate trigger {trigger_class.__name__}: {e}",
+                            workflow_definition=cls,
+                        ) from e
+
+                # Match by name
+                if trigger_name is not None and trigger_class.__trigger_name__ == trigger_name:
+                    try:
+                        return trigger_class(**inputs)
+                    except Exception as e:
+                        raise WorkflowInitializationException(
+                            message=f"Failed to instantiate trigger {trigger_class.__name__}: {e}",
+                            workflow_definition=cls,
+                        ) from e
 
                 trigger_classes.append(trigger_class)
 
-        raise WorkflowInitializationException(
-            message=f"No trigger class found with id {trigger_id} in workflow {cls.__name__}. "
-            f"Available trigger classes: {[trigger_class.__name__ for trigger_class in trigger_classes]}"
-        )
+        # Build helpful error message
+        if trigger_name is not None:
+            available_names = [trigger_class.__trigger_name__ for trigger_class in trigger_classes]
+            raise WorkflowInitializationException(
+                message=f"No trigger class found with name '{trigger_name}' in workflow {cls.__name__}. "
+                f"Available trigger names: {available_names}"
+            )
+        else:
+            raise WorkflowInitializationException(
+                message=f"No trigger class found with id {trigger_id} in workflow {cls.__name__}. "
+                f"Available trigger classes: {[trigger_class.__name__ for trigger_class in trigger_classes]}"
+            )
 
     @staticmethod
     def load_from_module(module_path: str) -> Type["BaseWorkflow"]:
@@ -874,6 +972,19 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
             raise WorkflowInitializationException(message=f"Invalid variable reference: {e}") from e
         except Exception as e:
             raise WorkflowInitializationException(message=f"Unexpected failure while loading module: {e}") from e
+
+        # Attempt to load optional display sidecar module to trigger node ID annotations
+        display_path = f"{module_path}.display"
+        try:
+            importlib.import_module(display_path)
+        except ModuleNotFoundError:
+            # No display package for this workflow; that's fine.
+            pass
+        except Exception as e:
+            raise WorkflowInitializationException(
+                message=f"Unexpected failure while loading display module '{display_path}': {e}"
+            ) from e
+
         workflows: List[Type[BaseWorkflow]] = []
         for name in dir(module):
             if name.startswith("__"):
@@ -905,6 +1016,35 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         for emitter in self.emitters:
             emitter.join()
 
+    @classmethod
+    def _validate_no_self_edges(cls) -> None:
+        """
+        Validate that the workflow graph doesn't contain unconditional self-edges (infinite loops).
+
+        A node is considered to have an unconditional self-edge if all of its ports target itself.
+
+        Args:
+            edges: List of edge dictionaries from the serialized workflow
+
+        Raises:
+            WorkflowInitializationException: If an unconditional self-edge is detected
+        """
+
+        for node in cls.get_all_nodes():
+            node_ports = [list(port.edges) for port in node.Ports]
+            if (
+                all(
+                    all(edge.to_node == node for edge in port_edges) and len(port_edges) > 0
+                    for port_edges in node_ports
+                )
+                and len(node_ports) > 0
+            ):
+                raise WorkflowInitializationException(
+                    message=f"Graph contains a self-edge ({node.__name__} >> {node.__name__}).",
+                    workflow_definition=cls,
+                    code=WorkflowErrorCode.INVALID_WORKFLOW,
+                )
+
 
 WorkflowExecutionInitiatedBody.model_rebuild()
 WorkflowExecutionFulfilledBody.model_rebuild()
@@ -920,6 +1060,7 @@ NodeExecutionRejectedBody.model_rebuild()
 NodeExecutionPausedBody.model_rebuild()
 NodeExecutionResumedBody.model_rebuild()
 NodeExecutionStreamingBody.model_rebuild()
+NodeExecutionLogBody.model_rebuild()
 
 WorkflowExecutionInitiatedEvent.model_rebuild()
 WorkflowExecutionFulfilledEvent.model_rebuild()
@@ -935,5 +1076,6 @@ NodeExecutionRejectedEvent.model_rebuild()
 NodeExecutionPausedEvent.model_rebuild()
 NodeExecutionResumedEvent.model_rebuild()
 NodeExecutionStreamingEvent.model_rebuild()
+NodeExecutionLogEvent.model_rebuild()
 
 StateMeta.model_rebuild()

vellum/workflows/workflows/tests/test_base_workflow.py

@@ -340,6 +340,32 @@ def test_workflow__unsupported_graph_item():
     assert "Unexpected graph type: <class 'int'>" in str(exc_info.value)
 
 
+def test_resolve_graph__non_class_item_in_set():
+    """Test that _resolve_graph properly handles non-class items in a set without crashing on issubclass()."""
+    # GIVEN a non-class value (a string, not a class)
+    # WHEN we call _resolve_graph with a set containing a non-class value
+    with pytest.raises(ValueError) as exc_info:
+        BaseWorkflow._resolve_graph({"not_a_class"})  # type: ignore
+
+    # THEN it should raise ValueError instead of crashing with "issubclass() arg 1 must be a class"
+    assert "Unexpected graph type:" in str(exc_info.value)
+    assert "<class 'str'>" in str(exc_info.value)
+
+
+def test_resolve_graph__non_class_value():
+    """Test that _resolve_graph properly handles non-class values without crashing on issubclass()."""
+    # GIVEN a non-class value (a string, not a class)
+    non_class_value = "not_a_class"
+
+    # WHEN we call _resolve_graph with a non-class value
+    with pytest.raises(ValueError) as exc_info:
+        BaseWorkflow._resolve_graph(non_class_value)  # type: ignore
+
+    # THEN it should raise ValueError instead of crashing with "issubclass() arg 1 must be a class"
+    assert "Unexpected graph type:" in str(exc_info.value)
+    assert "<class 'str'>" in str(exc_info.value)
+
+
 def test_base_workflow__deserialize_state():
     # GIVEN a state definition
     class State(BaseState):
@@ -783,3 +809,28 @@ def test_base_workflow__run_node_with_inputs():
     # AND the execution result should use the overridden and non-overridden attributes
     fulfilled_event = events[1]
     assert fulfilled_event.body.outputs.result == "overridden_overridden_value_default_value2_not_overridden"
+
+
+def test_base_workflow__invalid_graph__outgoing_edge_with_no_ports():
+    """Test that graph construction fails if we attempt to create an outgoing edge from a node with no ports."""
+
+    # GIVEN
+    class StartNode(BaseNode[BaseState]):
+        pass
+
+    class MyFinalOutput(BaseNode[BaseState]):
+        class Ports(BaseNode.Ports):
+            pass
+
+    class EndNode(BaseNode[BaseState]):
+        pass
+
+    # THEN
+    with pytest.raises(
+        ValueError,
+        match="Cannot create edges from graph because all terminal nodes have no ports defined: MyFinalOutput. "
+        + "Nodes with empty Ports classes cannot be connected to other nodes.",
+    ):
+
+        class InvalidWorkflow(BaseWorkflow[BaseInputs, BaseState]):
+            graph = StartNode >> MyFinalOutput >> EndNode

{vellum_ai-1.11.2.dist-info → vellum_ai-1.13.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vellum-ai
-Version: 1.11.2
+Version: 1.13.5
 Summary: 
 License: MIT
 Requires-Python: >=3.9,<4.0
@@ -20,10 +20,14 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
+Provides-Extra: mypy
+Provides-Extra: zuban
 Requires-Dist: Jinja2 (>=3.1.0,<4.0.0)
 Requires-Dist: click (>=8.1.7,<9.0.0)
 Requires-Dist: docker (>=7.1.0,<8.0.0)
 Requires-Dist: httpx (>=0.21.2)
+Requires-Dist: jsonschema (>=4.0.0)
+Requires-Dist: mypy (>=1.13.0) ; extra == "mypy"
 Requires-Dist: orderly-set (>=5.2.2,<6.0.0)
 Requires-Dist: publication (==0.0.3)
 Requires-Dist: pydantic (>=1.9.2)
@@ -36,6 +40,7 @@ Requires-Dist: pyyaml (>=6.0.0,<7.0.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
 Requires-Dist: tomli (>=2.0.0,<3.0.0)
 Requires-Dist: typing_extensions (>=4.0.0)
+Requires-Dist: zuban (>=0.4.2) ; extra == "zuban"
 Project-URL: Repository, https://github.com/vellum-ai/vellum-python-sdks
 Description-Content-Type: text/markdown