vellum-ai 0.10.3__py3-none-any.whl → 0.10.6__py3-none-any.whl

vellum/client/core/client_wrapper.py

@@ -17,7 +17,7 @@ class BaseClientWrapper:
         headers: typing.Dict[str, str] = {
             "X-Fern-Language": "Python",
             "X-Fern-SDK-Name": "vellum-ai",
-            "X-Fern-SDK-Version": "0.10.3",
+            "X-Fern-SDK-Version": "0.10.6",
         }
         headers["X_API_KEY"] = self.api_key
         return headers

vellum/workflows/events/tests/test_event.py

@@ -7,6 +7,7 @@ from deepdiff import DeepDiff
 
 from vellum.workflows.errors.types import VellumError, VellumErrorCode
 from vellum.workflows.events.node import NodeExecutionInitiatedBody, NodeExecutionInitiatedEvent
+from vellum.workflows.events.types import NodeParentContext, WorkflowParentContext
 from vellum.workflows.events.workflow import (
     WorkflowExecutionFulfilledBody,
     WorkflowExecutionFulfilledEvent,
@@ -73,6 +74,7 @@ module_root = name_parts[: name_parts.index("events")]
                         "foo": "bar",
                     },
                 },
+                "parent": None,
             },
         ),
         (
@@ -87,6 +89,14 @@ module_root = name_parts[: name_parts.index("events")]
                         MockNode.node_foo: "bar",
                     },
                 ),
+                parent=NodeParentContext(
+                    node_definition=MockNode,
+                    span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
+                    parent=WorkflowParentContext(
+                        workflow_definition=MockWorkflow,
+                        span_id=UUID("123e4567-e89b-12d3-a456-426614174000")
+                    )
+                )
             ),
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
@@ -104,6 +114,23 @@ module_root = name_parts[: name_parts.index("events")]
                         "node_foo": "bar",
                     },
                 },
+                "parent": {
+                    "node_definition": {
+                        "name": "MockNode",
+                        "module": module_root + ["events", "tests", "test_event"],
+                    },
+                    "parent": {
+                        "workflow_definition": {
+                            "name": "MockWorkflow",
+                            "module": module_root + ["events", "tests", "test_event"],
+                        },
+                        "type": "WORKFLOW",
+                        "parent": None,
+                        "span_id": "123e4567-e89b-12d3-a456-426614174000"
+                    },
+                    "type": "WORKFLOW_NODE",
+                    "span_id": "123e4567-e89b-12d3-a456-426614174000"
+                },
             },
         ),
         (
@@ -137,6 +164,7 @@ module_root = name_parts[: name_parts.index("events")]
                         "value": "foo",
                     },
                 },
+                "parent": None
             },
         ),
         (
@@ -168,6 +196,7 @@ module_root = name_parts[: name_parts.index("events")]
                         "example": "foo",
                     },
                 },
+                "parent": None,
             },
         ),
         (
@@ -201,6 +230,7 @@ module_root = name_parts[: name_parts.index("events")]
                         "code": "USER_DEFINED_ERROR",
                     },
                 },
+                "parent": None,
             },
         ),
     ],

vellum/workflows/events/types.py

@@ -2,15 +2,18 @@ from datetime import datetime
 from enum import Enum
 import json
 from uuid import UUID, uuid4
-from typing import Any, Dict, Literal
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, Type, Union
 
-from pydantic import Field
+from pydantic import Field, field_serializer
 
 from vellum.core.pydantic_utilities import UniversalBaseModel
-
 from vellum.workflows.state.encoder import DefaultStateEncoder
 from vellum.workflows.types.utils import datetime_now
 
+if TYPE_CHECKING:
+    from vellum.workflows.nodes.bases.base import BaseNode
+    from vellum.workflows.workflows.base import BaseWorkflow
+
 
 class WorkflowEventType(Enum):
     NODE = "NODE"
@@ -44,9 +47,60 @@ def default_serializer(obj: Any) -> Any:
     )
 
 
+class BaseParentContext(UniversalBaseModel):
+    span_id: UUID
+    parent: Optional['ParentContext'] = None
+
+
+class BaseDeploymentParentContext(BaseParentContext):
+    deployment_id: UUID
+    deployment_name: str
+    deployment_history_item_id: UUID
+    release_tag_id: UUID
+    release_tag_name: str
+    external_id: Optional[str]
+
+
+class WorkflowDeploymentParentContext(BaseDeploymentParentContext):
+    type: Literal["WORKFLOW_RELEASE_TAG"] = "WORKFLOW_RELEASE_TAG"
+    workflow_version_id: UUID
+
+
+class PromptDeploymentParentContext(BaseDeploymentParentContext):
+    type: Literal["PROMPT_RELEASE_TAG"] = "PROMPT_RELEASE_TAG"
+    prompt_version_id: UUID
+
+
+class NodeParentContext(BaseParentContext):
+    type: Literal["WORKFLOW_NODE"] = "WORKFLOW_NODE"
+    node_definition: Type['BaseNode']
+
+    @field_serializer("node_definition")
+    def serialize_node_definition(self, definition: Type, _info: Any) -> Dict[str, Any]:
+        return serialize_type_encoder(definition)
+
+
+class WorkflowParentContext(BaseParentContext):
+    type: Literal["WORKFLOW"] = "WORKFLOW"
+    workflow_definition: Type['BaseWorkflow']
+
+    @field_serializer("workflow_definition")
+    def serialize_workflow_definition(self, definition: Type, _info: Any) -> Dict[str, Any]:
+        return serialize_type_encoder(definition)
+
+
+ParentContext = Union[
+    NodeParentContext,
+    WorkflowParentContext,
+    PromptDeploymentParentContext,
+    WorkflowDeploymentParentContext,
+]
+
+
 class BaseEvent(UniversalBaseModel):
     id: UUID = Field(default_factory=uuid4)
     timestamp: datetime = Field(default_factory=default_datetime_factory)
     api_version: Literal["2024-10-25"] = "2024-10-25"
     trace_id: UUID
     span_id: UUID
+    parent: Optional['ParentContext'] = None

vellum/workflows/nodes/__init__.py

@@ -1,5 +1,5 @@
 from vellum.workflows.nodes.bases import BaseNode
-from vellum.workflows.nodes.core import (ErrorNode, InlineSubworkflowNode, MapNode, RetryNode, TemplatingNode, TryNode,)
+from vellum.workflows.nodes.core import ErrorNode, InlineSubworkflowNode, MapNode, RetryNode, TemplatingNode, TryNode
 from vellum.workflows.nodes.displayable import (
     APINode,
     CodeExecutionNode,
@@ -7,6 +7,7 @@ from vellum.workflows.nodes.displayable import (
     FinalOutputNode,
     GuardrailNode,
     InlinePromptNode,
+    NoteNode,
     PromptDeploymentNode,
     SearchNode,
     SubworkflowDeploymentNode,
@@ -28,20 +29,18 @@ __all__ = [
     "TemplatingNode",
     "TryNode",
     # Displayable Base Nodes
-    "BaseSearchNode",
     "BaseInlinePromptNode",
     "BasePromptDeploymentNode",
+    "BaseSearchNode",
     # Displayable Nodes
     "APINode",
     "CodeExecutionNode",
+    "ConditionalNode",
+    "FinalOutputNode",
     "GuardrailNode",
     "InlinePromptNode",
+    "NoteNode",
     "PromptDeploymentNode",
     "SearchNode",
-    "ConditionalNode",
-    "GuardrailNode",
     "SubworkflowDeploymentNode",
-    "FinalOutputNode",
-    "PromptDeploymentNode",
-    "SearchNode",
 ]

vellum/workflows/nodes/bases/base.py

@@ -215,7 +215,6 @@ class BaseNode(Generic[StateType], metaclass=BaseNodeMeta):
     #   https://app.shortcut.com/vellum/story/4008/auto-inherit-basenodeoutputs-in-outputs-classes
     class Outputs(BaseOutputs):
         _node_class: Optional[Type["BaseNode"]] = None
-        pass
 
     class Ports(NodePorts):
         default = Port(default=True)

vellum/workflows/nodes/core/inline_subworkflow_node/node.py

@@ -25,6 +25,7 @@ class InlineSubworkflowNode(BaseSubworkflowNode[StateType], Generic[StateType, W
     def run(self) -> Iterator[BaseOutput]:
         subworkflow = self.subworkflow(
             parent_state=self.state,
+            context=self._context,
         )
         subworkflow_stream = subworkflow.stream(
             inputs=self._compile_subworkflow_inputs(),
@@ -56,7 +57,7 @@ class InlineSubworkflowNode(BaseSubworkflowNode[StateType], Generic[StateType, W
         if outputs is None:
             raise NodeException(
                 message="Expected to receive outputs from Workflow Deployment",
-                code=VellumErrorCode.INTERNAL_ERROR,
+                code=VellumErrorCode.INVALID_OUTPUTS,
             )
 
         # For any outputs somehow in our final fulfilled outputs array,

vellum/workflows/nodes/core/map_node/node.py

@@ -89,7 +89,7 @@ class MapNode(BaseNode, Generic[StateType, MapNodeItemType]):
         return self.Outputs(**mapped_items)
 
     def _run_subworkflow(self, *, item: MapNodeItemType, index: int) -> None:
-        subworkflow = self.subworkflow(parent_state=self.state)
+        subworkflow = self.subworkflow(parent_state=self.state, context=self._context)
         events = subworkflow.stream(inputs=self.SubworkflowInputs(index=index, item=item, all_items=self.items))
 
         for event in events:

vellum/workflows/nodes/core/retry_node/node.py

@@ -43,6 +43,7 @@ class RetryNode(BaseNode[StateType], Generic[StateType], metaclass=_RetryNodeMet
             attempt_number = index + 1
             subworkflow = self.subworkflow(
                 parent_state=self.state,
+                context=self._context,
             )
             terminal_event = subworkflow.run(
                 inputs=self.SubworkflowInputs(attempt_number=attempt_number),

vellum/workflows/nodes/core/templating_node/node.py

@@ -49,7 +49,11 @@ class _TemplatingNodeMeta(BaseNodeMeta):
         if not isinstance(parent, _TemplatingNodeMeta):
             raise ValueError("TemplatingNode must be created with the TemplatingNodeMeta metaclass")
 
-        parent.__dict__["Outputs"].__annotations__["result"] = parent.get_output_type()
+        annotations = parent.__dict__["Outputs"].__annotations__
+        parent.__dict__["Outputs"].__annotations__ = {
+            **annotations,
+            "result": parent.get_output_type(),
+        }
         return parent
 
     def get_output_type(cls) -> Type:

vellum/workflows/nodes/core/try_node/node.py

@@ -1,10 +1,13 @@
-from typing import TYPE_CHECKING, Any, Callable, Dict, Generic, Optional, Tuple, Type, TypeVar
+import sys
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, Callable, Dict, Generic, Iterator, Optional, Set, Tuple, Type, TypeVar, cast
 
 from vellum.workflows.errors.types import VellumError, VellumErrorCode
 from vellum.workflows.exceptions import NodeException
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.nodes.bases.base import BaseNodeMeta
-from vellum.workflows.outputs.base import BaseOutputs
+from vellum.workflows.nodes.utils import ADORNMENT_MODULE_NAME
+from vellum.workflows.outputs.base import BaseOutput, BaseOutputs
 from vellum.workflows.types.generics import StateType
 
 if TYPE_CHECKING:
@@ -56,33 +59,60 @@ class TryNode(BaseNode[StateType], Generic[StateType], metaclass=_TryNodeMeta):
     class Outputs(BaseNode.Outputs):
         error: Optional[VellumError] = None
 
-    def run(self) -> Outputs:
+    def run(self) -> Iterator[BaseOutput]:
         subworkflow = self.subworkflow(
             parent_state=self.state,
+            context=self._context,
         )
-        terminal_event = subworkflow.run()
-
-        if terminal_event.name == "workflow.execution.fulfilled":
-            outputs = self.Outputs()
-            for descriptor, value in terminal_event.outputs:
-                setattr(outputs, descriptor.name, value)
-            return outputs
-        elif terminal_event.name == "workflow.execution.paused":
+        subworkflow_stream = subworkflow.stream()
+
+        outputs: Optional[BaseOutputs] = None
+        exception: Optional[NodeException] = None
+        fulfilled_output_names: Set[str] = set()
+
+        for event in subworkflow_stream:
+            if exception:
+                continue
+
+            if event.name == "workflow.execution.streaming":
+                if event.output.is_fulfilled:
+                    fulfilled_output_names.add(event.output.name)
+                yield event.output
+            elif event.name == "workflow.execution.fulfilled":
+                outputs = event.outputs
+            elif event.name == "workflow.execution.paused":
+                exception = NodeException(
+                    code=VellumErrorCode.INVALID_OUTPUTS,
+                    message="Subworkflow unexpectedly paused within Try Node",
+                )
+            elif event.name == "workflow.execution.rejected":
+                if self.on_error_code and self.on_error_code != event.error.code:
+                    exception = NodeException(
+                        code=VellumErrorCode.INVALID_OUTPUTS,
+                        message=f"""Unexpected rejection: {event.error.code.value}.
+Message: {event.error.message}""",
+                    )
+                else:
+                    outputs = self.Outputs(error=event.error)
+
+        if exception:
+            raise exception
+
+        if outputs is None:
             raise NodeException(
                 code=VellumErrorCode.INVALID_OUTPUTS,
-                message="Subworkflow unexpectedly paused within Try Node",
-            )
-        elif self.on_error_code and self.on_error_code != terminal_event.error.code:
-            raise NodeException(
-                code=VellumErrorCode.INVALID_OUTPUTS,
-                message=f"""Unexpected rejection: {terminal_event.error.code.value}.
-Message: {terminal_event.error.message}""",
-            )
-        else:
-            return self.Outputs(
-                error=terminal_event.error,
+                message="Expected to receive outputs from Try Node's subworkflow",
             )
 
+        # For any outputs somehow in our final fulfilled outputs array,
+        # but not fulfilled by the stream.
+        for descriptor, value in outputs:
+            if descriptor.name not in fulfilled_output_names:
+                yield BaseOutput(
+                    name=descriptor.name,
+                    value=value,
+                )
+
     @classmethod
     def wrap(cls, on_error_code: Optional[VellumErrorCode] = None) -> Callable[..., Type["TryNode"]]:
         _on_error_code = on_error_code
@@ -100,11 +130,20 @@ Message: {terminal_event.error.message}""",
                 class Outputs(inner_cls.Outputs):  # type: ignore[name-defined]
                     pass
 
-            class WrappedNode(TryNode[StateType]):
-                on_error_code = _on_error_code
-
-                subworkflow = Subworkflow
-
+            dynamic_module = f"{inner_cls.__module__}.{inner_cls.__name__}.{ADORNMENT_MODULE_NAME}"
+            # This dynamic module allows calls to `type_hints` to work
+            sys.modules[dynamic_module] = ModuleType(dynamic_module)
+
+            # We use a dynamic wrapped node class to be uniquely tied to this `inner_cls` node during serialization
+            WrappedNode = type(
+                cls.__name__,
+                (TryNode,),
+                {
+                    "__module__": dynamic_module,
+                    "on_error_code": _on_error_code,
+                    "subworkflow": Subworkflow,
+                },
+            )
             return WrappedNode
 
         return decorator

vellum/workflows/nodes/core/try_node/tests/test_node.py

@@ -1,12 +1,15 @@
 import pytest
 
+from vellum.client import Vellum
 from vellum.workflows.errors.types import VellumError, VellumErrorCode
 from vellum.workflows.exceptions import NodeException
 from vellum.workflows.inputs.base import BaseInputs
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.nodes.core.try_node.node import TryNode
 from vellum.workflows.outputs import BaseOutputs
+from vellum.workflows.outputs.base import BaseOutput
 from vellum.workflows.state.base import BaseState, StateMeta
+from vellum.workflows.state.context import WorkflowContext
 
 
 def test_try_node__on_error_code__successfully_caught():
@@ -21,11 +24,15 @@ def test_try_node__on_error_code__successfully_caught():
 
     # WHEN the node is run and throws a PROVIDER_ERROR
     node = TestNode(state=BaseState())
-    outputs = node.run()
-
-    # THEN the exception is retried
-    assert outputs == {
-        "error": VellumError(message="This will be caught", code=VellumErrorCode.PROVIDER_ERROR),
+    outputs = [o for o in node.run()]
+
+    # THEN the exception is caught and returned
+    assert len(outputs) == 2
+    assert set(outputs) == {
+        BaseOutput(name="value"),
+        BaseOutput(
+            name="error", value=VellumError(message="This will be caught", code=VellumErrorCode.PROVIDER_ERROR)
+        ),
     }
 
 
@@ -42,7 +49,7 @@ def test_try_node__retry_on_error_code__missed():
     # WHEN the node is run and throws a different exception
     node = TestNode(state=BaseState())
     with pytest.raises(NodeException) as exc_info:
-        node.run()
+        list(node.run())
 
     # THEN the exception is not caught
     assert exc_info.value.message == "Unexpected rejection: INTERNAL_ERROR.\nMessage: This will be missed"
@@ -76,7 +83,31 @@ def test_try_node__use_parent_inputs_and_state():
             meta=StateMeta(workflow_inputs=Inputs(foo="foo")),
         ),
     )
-    outputs = node.run()
+    outputs = list(node.run())
 
     # THEN the data is used successfully
-    assert outputs == {"value": "foo bar"}
+    assert len(outputs) == 1
+    assert outputs[-1] == BaseOutput(name="value", value="foo bar")
+
+
+def test_try_node__use_parent_execution_context():
+    # GIVEN a try node that uses node context to use the vellum client
+    @TryNode.wrap()
+    class TestNode(BaseNode):
+        class Outputs(BaseOutputs):
+            key: str
+
+        def run(self) -> Outputs:
+            return self.Outputs(key=self._context.vellum_client.ad_hoc._client_wrapper.api_key)
+
+    # WHEN the node is run with a custom vellum client
+    node = TestNode(
+        context=WorkflowContext(
+            _vellum_client=Vellum(api_key="test-key"),
+        )
+    )
+    outputs = list(node.run())
+
+    # THEN the inner node had access to the key
+    assert len(outputs) == 1
+    assert outputs[-1] == BaseOutput(name="key", value="test-key")

vellum/workflows/nodes/displayable/__init__.py

@@ -9,6 +9,7 @@ from .final_output_node import FinalOutputNode
 from .guardrail_node import GuardrailNode
 from .inline_prompt_node import InlinePromptNode
 from .merge_node import MergeNode
+from .note_node import NoteNode
 from .prompt_deployment_node import PromptDeploymentNode
 from .search_node import SearchNode
 from .subworkflow_deployment_node import SubworkflowDeploymentNode
@@ -23,6 +24,7 @@ __all__ = [
     "GuardrailNode",
     "MapNode",
     "MergeNode",
+    "NoteNode",
     "SubworkflowDeploymentNode",
     "PromptDeploymentNode",
     "SearchNode",

vellum/workflows/nodes/displayable/bases/api_node/node.py

@@ -8,7 +8,7 @@ from vellum.workflows.errors.types import VellumErrorCode
 from vellum.workflows.exceptions import NodeException
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.outputs import BaseOutputs
-from vellum.workflows.types.core import JsonObject, VellumSecret
+from vellum.workflows.types.core import Json, JsonObject, VellumSecret
 from vellum.workflows.types.generics import StateType
 
 
@@ -26,11 +26,11 @@ class BaseAPINode(BaseNode, Generic[StateType]):
     url: str
     method: APIRequestMethod
     data: Optional[str] = None
-    json: Optional["JsonObject"] = None
+    json: Optional["Json"] = None
     headers: Optional[Dict[str, Union[str, VellumSecret]]] = None
 
     class Outputs(BaseOutputs):
-        json: Optional["JsonObject"]
+        json: Optional["Json"]
         headers: Dict[str, str]
         status_code: int
         text: str

vellum/workflows/nodes/displayable/code_execution_node/node.py

@@ -19,7 +19,6 @@ from vellum import (
     VellumValue,
 )
 from vellum.core import RequestOptions
-
 from vellum.workflows.errors.types import VellumErrorCode
 from vellum.workflows.exceptions import NodeException
 from vellum.workflows.nodes.bases import BaseNode
@@ -44,7 +43,11 @@ class _CodeExecutionNodeMeta(BaseNodeMeta):
         if not isinstance(parent, _CodeExecutionNodeMeta):
             raise ValueError("CodeExecutionNode must be created with the CodeExecutionNodeMeta metaclass")
 
-        parent.__dict__["Outputs"].__annotations__["result"] = parent.get_output_type()
+        annotations = parent.__dict__["Outputs"].__annotations__
+        parent.__dict__["Outputs"].__annotations__ = {
+            **annotations,
+            "result": parent.get_output_type(),
+        }
         return parent
 
     def get_output_type(cls) -> Type:

vellum/workflows/nodes/displayable/final_output_node/node.py

@@ -16,9 +16,13 @@ class _FinalOutputNodeMeta(BaseNodeMeta):
 
         # We use the compiled class to infer the output type for the Outputs.value descriptor.
         if not isinstance(parent, _FinalOutputNodeMeta):
-            raise ValueError("CodeExecutionNode must be created with the CodeExecutionNodeMeta metaclass")
+            raise ValueError("FinalOutputNode must be created with the FinalOutputNodeMeta metaclass")
 
-        parent.__dict__["Outputs"].__annotations__["value"] = parent.get_output_type()
+        annotations = parent.__dict__["Outputs"].__annotations__
+        parent.__dict__["Outputs"].__annotations__ = {
+            **annotations,
+            "value": parent.get_output_type(),
+        }
         return parent
 
     def get_output_type(cls) -> Type:

vellum/workflows/nodes/displayable/note_node/__init__.py

@@ -0,0 +1,5 @@
+from .node import NoteNode
+
+__all__ = [
+    "NoteNode",
+]

vellum/workflows/nodes/displayable/note_node/node.py

@@ -0,0 +1,10 @@
+from vellum.workflows.nodes.bases import BaseNode
+
+
+class NoteNode(BaseNode):
+    """
+    A no-op Node purely used to display a note in the Vellum UI.
+    """
+
+    def run(self) -> BaseNode.Outputs:
+        raise RuntimeError("NoteNode should never be run")

vellum/workflows/nodes/displayable/tests/test_inline_text_prompt_node.py

@@ -11,13 +11,12 @@ from vellum import (
     StringVellumValue,
     VellumError,
 )
-
-from vellum.workflows.constants import UNDEF
-from vellum.workflows.errors import VellumError as WacVellumError
+from vellum.workflows.errors import VellumError as SdkVellumError
 from vellum.workflows.errors.types import VellumErrorCode
 from vellum.workflows.inputs import BaseInputs
 from vellum.workflows.nodes import InlinePromptNode
 from vellum.workflows.nodes.core.try_node.node import TryNode
+from vellum.workflows.outputs.base import BaseOutput
 from vellum.workflows.state import BaseState
 from vellum.workflows.state.base import StateMeta
 
@@ -136,13 +135,13 @@ def test_inline_text_prompt_node__catch_provider_error(vellum_adhoc_prompt_clien
             meta=StateMeta(workflow_inputs=Inputs(input="Say something.")),
         )
     )
-    outputs = node.run()
+    outputs = list(node.run())
 
     # THEN the node should have produced the outputs we expect
-    # We need mypy support for annotations to remove these type ignores
-    # https://app.shortcut.com/vellum/story/4890
-    assert outputs.error == WacVellumError(  # type: ignore[attr-defined]
-        message="OpenAI failed",
-        code=VellumErrorCode.PROVIDER_ERROR,
-    )
-    assert outputs.text is UNDEF  # type: ignore[attr-defined]
+    assert BaseOutput(
+        name="error",
+        value=SdkVellumError(
+            message="OpenAI failed",
+            code=VellumErrorCode.PROVIDER_ERROR,
+        ),
+    ) in outputs

vellum/workflows/nodes/utils.py

@@ -5,6 +5,8 @@ from vellum.workflows.nodes import BaseNode
 from vellum.workflows.references import NodeReference
 from vellum.workflows.types.generics import NodeType
 
+ADORNMENT_MODULE_NAME = "<adornment>"
+
 
 @cache
 def get_wrapped_node(node: Type[NodeType]) -> Type[BaseNode]: