vellum-ai 1.1.1__py3-none-any.whl → 1.1.3__py3-none-any.whl

vellum/client/types/workflow_execution_span.py

@@ -12,6 +12,7 @@ from .workflow_sandbox_parent_context import WorkflowSandboxParentContext
 import typing
 from .vellum_workflow_execution_event import VellumWorkflowExecutionEvent
 from .workflow_execution_span_attributes import WorkflowExecutionSpanAttributes
+from .workflow_execution_usage_calculation_fulfilled_body import WorkflowExecutionUsageCalculationFulfilledBody
 import datetime as dt
 from ..core.pydantic_utilities import IS_PYDANTIC_V2
 import pydantic
@@ -21,6 +22,7 @@ class WorkflowExecutionSpan(UniversalBaseModel):
     name: typing.Literal["workflow.execution"] = "workflow.execution"
     events: typing.List[VellumWorkflowExecutionEvent]
     attributes: WorkflowExecutionSpanAttributes
+    usage_result: typing.Optional[WorkflowExecutionUsageCalculationFulfilledBody] = None
     span_id: str
     start_ts: dt.datetime
     end_ts: dt.datetime

vellum/client/types/workflow_execution_usage_calculation_fulfilled_body.py

@@ -0,0 +1,22 @@
+# This file was auto-generated by Fern from our API Definition.
+
+from ..core.pydantic_utilities import UniversalBaseModel
+import typing
+from .ml_model_usage_wrapper import MlModelUsageWrapper
+from .price import Price
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+import pydantic
+
+
+class WorkflowExecutionUsageCalculationFulfilledBody(UniversalBaseModel):
+    usage: typing.List[MlModelUsageWrapper]
+    cost: typing.List[Price]
+
+    if IS_PYDANTIC_V2:
+        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
+    else:
+
+        class Config:
+            frozen = True
+            smart_union = True
+            extra = pydantic.Extra.allow

vellum/prompts/blocks/compilation.py

@@ -142,29 +142,41 @@ def compile_prompt_blocks(
             )
             compiled_blocks.append(function_call_block)
 
-        elif block.block_type == "IMAGE":
-            image_block = CompiledValuePromptBlock(
-                content=ImageVellumValue(
-                    value=VellumImage(
+        elif block.block_type == "AUDIO":
+            audio_block = CompiledValuePromptBlock(
+                content=AudioVellumValue(
+                    value=VellumAudio(
                         src=block.src,
                         metadata=block.metadata,
                     ),
                 ),
                 cache_config=block.cache_config,
             )
-            compiled_blocks.append(image_block)
+            compiled_blocks.append(audio_block)
 
-        elif block.block_type == "AUDIO":
-            audio_block = CompiledValuePromptBlock(
-                content=AudioVellumValue(
-                    value=VellumAudio(
+        # elif block.block_type == "VIDEO":
+        #     video_block = CompiledValuePromptBlock(
+        #         content=VideoVellumValue(
+        #             value=VellumVideo(
+        #                 src=block.src,
+        #                 metadata=block.metadata,
+        #             ),
+        #         ),
+        #         cache_config=block.cache_config,
+        #     )
+        #     compiled_blocks.append(video_block)
+
+        elif block.block_type == "IMAGE":
+            image_block = CompiledValuePromptBlock(
+                content=ImageVellumValue(
+                    value=VellumImage(
                         src=block.src,
                         metadata=block.metadata,
                     ),
                 ),
                 cache_config=block.cache_config,
             )
-            compiled_blocks.append(audio_block)
+            compiled_blocks.append(image_block)
 
         elif block.block_type == "DOCUMENT":
             document_block = CompiledValuePromptBlock(

vellum/types/vellum_video.py

@@ -0,0 +1,3 @@
+# WARNING: This file will be removed in a future release. Please import from "vellum.client" instead.
+
+from vellum.client.types.vellum_video import *

vellum/types/vellum_video_request.py

@@ -0,0 +1,3 @@
+# WARNING: This file will be removed in a future release. Please import from "vellum.client" instead.
+
+from vellum.client.types.vellum_video_request import *

vellum/types/video_chat_message_content.py

@@ -0,0 +1,3 @@
+# WARNING: This file will be removed in a future release. Please import from "vellum.client" instead.
+
+from vellum.client.types.video_chat_message_content import *

vellum/types/video_chat_message_content_request.py

@@ -0,0 +1,3 @@
+# WARNING: This file will be removed in a future release. Please import from "vellum.client" instead.
+
+from vellum.client.types.video_chat_message_content_request import *

vellum/types/video_prompt_block.py

@@ -0,0 +1,3 @@
+# WARNING: This file will be removed in a future release. Please import from "vellum.client" instead.
+
+from vellum.client.types.video_prompt_block import *

vellum/types/video_vellum_value.py

@@ -0,0 +1,3 @@
+# WARNING: This file will be removed in a future release. Please import from "vellum.client" instead.
+
+from vellum.client.types.video_vellum_value import *

vellum/types/video_vellum_value_request.py

@@ -0,0 +1,3 @@
+# WARNING: This file will be removed in a future release. Please import from "vellum.client" instead.
+
+from vellum.client.types.video_vellum_value_request import *

vellum/types/workflow_execution_usage_calculation_fulfilled_body.py

@@ -0,0 +1,3 @@
+# WARNING: This file will be removed in a future release. Please import from "vellum.client" instead.
+
+from vellum.client.types.workflow_execution_usage_calculation_fulfilled_body import *

vellum/workflows/events/workflow.py

@@ -41,6 +41,17 @@ class _BaseWorkflowEvent(BaseEvent):
     def workflow_definition(self) -> Type["BaseWorkflow"]:
         return self.body.workflow_definition
 
+    @property
+    def monitoring_url(self) -> Optional[str]:
+        """
+        Get the monitoring URL for this workflow execution.
+
+        Returns:
+            The URL to view execution details in Vellum UI, or None if monitoring is disabled
+            or context is not available.
+        """
+        return None
+
 
 class NodeEventDisplayContext(UniversalBaseModel):
     input_display: Dict[str, UUID]

vellum/workflows/graph/graph.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Iterator, List, Set, Type, Union
+from typing import TYPE_CHECKING, Iterator, List, Optional, Set, Type, Union
 
 from orderly_set import OrderedSet
 
@@ -154,3 +154,105 @@ class Graph:
         for edge in edges:
             if edge not in self._edges:
                 self._edges.append(edge)
+
+    def __str__(self) -> str:
+        """
+        Return a visual ASCII representation of the graph showing the flow structure.
+        """
+        if not self._edges and not self._entrypoints:
+            return "Graph(empty)"
+
+        if not self._edges:
+            if len(self._entrypoints) == 1:
+                port = next(iter(self._entrypoints))
+                return f"Graph: {self._get_port_name(port)}"
+            else:
+                port_names = [self._get_port_name(port) for port in self._entrypoints]
+                return f"Graph: [{', '.join(port_names)}]"
+
+        return self._build_flow_diagram()
+
+    def _build_flow_diagram(self) -> str:
+        """Build a connected flow diagram showing the graph structure."""
+        lines = ["Graph:"]
+
+        adjacency: dict[str, list[str]] = {}
+        all_nodes = set()
+
+        for edge in self._edges:
+            source_node = edge.from_port.node_class.__name__
+            target_node = edge.to_node.__name__
+
+            all_nodes.add(source_node)
+            all_nodes.add(target_node)
+
+            if source_node not in adjacency:
+                adjacency[source_node] = []
+            adjacency[source_node].append(target_node)
+
+        target_nodes = set()
+        for edges in adjacency.values():
+            target_nodes.update(edges)
+
+        root_nodes = []
+        for port in self._entrypoints:
+            node_name = port.node_class.__name__
+            if node_name not in target_nodes:
+                root_nodes.append(node_name)
+
+        if not root_nodes and self._entrypoints:
+            root_nodes = [next(iter(self._entrypoints)).node_class.__name__]
+
+        visited = set()
+        currently_visiting = set()
+
+        def render_node(node: str, prefix: str = "  ", is_last: bool = True, path: Optional[List[str]] = None) -> None:
+            if path is None:
+                path = []
+
+            if node in currently_visiting:
+                lines.append(f"{prefix}{'└─' if is_last else '├─'} {node} ⟲ (loops back)")
+                return
+
+            if node in visited:
+                lines.append(f"{prefix}{'└─' if is_last else '├─'} {node} → (see above)")
+                return
+
+            visited.add(node)
+            currently_visiting.add(node)
+
+            lines.append(f"{prefix}{'└─' if is_last else '├─'} {node}")
+
+            if node in adjacency:
+                children = adjacency[node]
+                for i, child in enumerate(children):
+                    child_is_last = i == len(children) - 1
+                    next_prefix = prefix + ("   " if is_last else "│  ")
+                    render_node(child, next_prefix, child_is_last, path + [node])
+
+            currently_visiting.remove(node)
+
+        for i, root in enumerate(root_nodes):
+            is_last_root = i == len(root_nodes) - 1
+            render_node(root, "  ", is_last_root)
+
+        return "\n".join(lines)
+
+    def _get_port_name(self, port: "Port") -> str:
+        """Get a readable name for a port."""
+        try:
+            if hasattr(port, "node_class") and hasattr(port.node_class, "__name__"):
+                node_name = port.node_class.__name__
+                port_name = getattr(port, "name", "unknown")
+                return f"{node_name}.{port_name}"
+            else:
+                return str(port)
+        except Exception:
+            return f"<Port:{getattr(port, 'name', 'unknown')}>"
+
+    def _get_node_name(self, node: Type["BaseNode"]) -> str:
+        """Get a readable name for a node."""
+        try:
+            return getattr(node, "__name__", str(node))
+        except Exception:
+            return "<Node:unknown>"

vellum/workflows/graph/tests/test_graph.py

@@ -484,3 +484,102 @@ def test_graph__set_to_graph():
 
     # AND two edges
     assert len(list(graph.edges)) == 2
+
+
+def test_graph__str_simple_linear():
+    # GIVEN a simple linear graph: A -> B -> C
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    class NodeC(BaseNode):
+        pass
+
+    graph = NodeA >> NodeB >> NodeC
+
+    # WHEN we convert the graph to string
+    result = str(graph)
+
+    # THEN it shows the linear flow structure
+    expected_lines = ["Graph:", "  └─ NodeA", "     └─ NodeB", "        └─ NodeC"]
+    assert result == "\n".join(expected_lines)
+
+
+def test_graph__str_with_branching():
+    # GIVEN a graph with branching: A -> {B, C}
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    class NodeC(BaseNode):
+        pass
+
+    graph = NodeA >> {NodeB, NodeC}
+
+    # WHEN we convert the graph to string
+    result = str(graph)
+
+    # THEN it shows the branching structure
+    # Note: The order might vary due to set ordering, so we check for the structure
+    lines = result.split("\n")
+    assert lines[0] == "Graph:"
+    assert lines[1] == "  └─ NodeA"
+
+    # Should have two branches (order may vary)
+    branch_lines = [line.strip() for line in lines[2:] if line.strip()]
+    assert len(branch_lines) == 2
+    assert any("NodeB" in line for line in branch_lines)
+    assert any("NodeC" in line for line in branch_lines)
+    assert all(line.startswith("├─ ") or line.startswith("└─ ") for line in branch_lines)
+
+
+def test_graph__str_with_loop():
+    # GIVEN a graph with a loop: A -> B -> A (loop back)
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    # Create the loop manually using edges
+    edge1 = Edge(NodeA.Ports.default, NodeB)
+    edge2 = Edge(NodeB.Ports.default, NodeA)
+
+    graph = Graph(entrypoints={NodeA.Ports.default}, edges=[edge1, edge2], terminals={NodeA.Ports.default})
+
+    # WHEN we convert the graph to string
+    result = str(graph)
+
+    # THEN it shows the loop with cycle detection
+    expected_lines = ["Graph:", "  └─ NodeA", "     └─ NodeB", "        └─ NodeA ⟲ (loops back)"]
+    assert result == "\n".join(expected_lines)
+
+
+def test_graph__str_empty_graph():
+    # GIVEN an empty graph
+    graph = Graph(entrypoints=set(), edges=[], terminals=set())
+
+    # WHEN we convert the graph to string
+    result = str(graph)
+
+    # THEN it shows empty graph message
+    assert result == "Graph(empty)"
+
+
+def test_graph__str_single_node():
+    # GIVEN a graph with just one node and no edges
+    class SingleNode(BaseNode):
+        pass
+
+    graph = Graph.from_node(SingleNode)
+
+    # WHEN we convert the graph to string
+    result = str(graph)
+
+    # THEN it shows the single node
+    assert "SingleNode.default" in result
+    assert "Graph:" in result

vellum/workflows/nodes/bases/base.py

@@ -8,6 +8,7 @@ from typing import Any, Dict, Generic, Iterator, Optional, Set, Tuple, Type, Typ
 
 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 is_unresolved, resolve_value
 from vellum.workflows.errors.types import WorkflowErrorCode
 from vellum.workflows.events.node import NodeExecutionStreamingEvent
@@ -302,7 +303,14 @@ class BaseNode(Generic[StateType], ABC, metaclass=BaseNodeMeta):
                     if not descriptor.instance:
                         continue
 
-                    resolved_value = resolve_value(descriptor.instance, state, path=descriptor.name)
+                    try:
+                        resolved_value = resolve_value(descriptor.instance, state, path=descriptor.name)
+                    except InvalidExpressionException as e:
+                        raise NodeException(
+                            message=str(e),
+                            code=WorkflowErrorCode.INVALID_INPUTS,
+                        ) from e
+
                     if is_unresolved(resolved_value):
                         return False
 

vellum/workflows/nodes/displayable/bases/utils.py

@@ -35,8 +35,9 @@ VELLUM_VALUE_REQUEST_TUPLE = (
     StringVellumValueRequest,
     NumberVellumValueRequest,
     JsonVellumValueRequest,
-    ImageVellumValueRequest,
     AudioVellumValueRequest,
+    # VideoVellumValueRequest,
+    ImageVellumValueRequest,
     FunctionCallVellumValueRequest,
     ErrorVellumValueRequest,
     ArrayVellumValueRequest,
@@ -78,8 +79,9 @@ def primitive_to_vellum_value(value: Any) -> VellumValue:
             StringVellumValue,
             NumberVellumValue,
             JsonVellumValue,
-            ImageVellumValue,
             AudioVellumValue,
+            # VideoVellumValue,
+            ImageVellumValue,
             FunctionCallVellumValue,
             ErrorVellumValue,
             ArrayVellumValue,

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

@@ -16,7 +16,7 @@ from vellum.workflows.nodes.displayable.tool_calling_node.utils import (
     create_function_node,
     create_mcp_tool_node,
     create_router_node,
-    create_tool_router_node,
+    create_tool_prompt_node,
     get_function_name,
     get_mcp_tool_name,
     hydrate_mcp_tool_definitions,
@@ -78,7 +78,7 @@ class ToolCallingNode(BaseNode[StateType], Generic[StateType]):
                 graph = self._graph
 
                 class Outputs(BaseWorkflow.Outputs):
-                    text: str = self.tool_router_node.Outputs.text
+                    text: str = self.tool_prompt_node.Outputs.text
                     chat_history: List[ChatMessage] = ToolCallingState.chat_history
 
             subworkflow = ToolCallingWorkflow(
@@ -137,7 +137,7 @@ class ToolCallingNode(BaseNode[StateType], Generic[StateType]):
                 )
 
     def _build_graph(self) -> None:
-        self.tool_router_node = create_tool_router_node(
+        self.tool_prompt_node = create_tool_prompt_node(
             ml_model=self.ml_model,
             blocks=self.blocks,
             functions=self.functions,
@@ -146,9 +146,10 @@ class ToolCallingNode(BaseNode[StateType], Generic[StateType]):
             max_prompt_iterations=self.max_prompt_iterations,
         )
 
+        # Create the router node (handles routing logic only)
         self.router_node = create_router_node(
             functions=self.functions,
-            tool_router_node=self.tool_router_node,
+            tool_prompt_node=self.tool_prompt_node,
         )
 
         self._function_nodes = {}
@@ -160,29 +161,29 @@ class ToolCallingNode(BaseNode[StateType], Generic[StateType]):
 
                     self._function_nodes[function_name] = create_mcp_tool_node(
                         tool_def=tool_definition,
-                        tool_router_node=self.tool_router_node,
+                        tool_prompt_node=self.tool_prompt_node,
                     )
             else:
                 function_name = get_function_name(function)
 
                 self._function_nodes[function_name] = create_function_node(
                     function=function,
-                    tool_router_node=self.tool_router_node,
+                    tool_prompt_node=self.tool_prompt_node,
                 )
 
-        graph_set = set()
+        graph: Graph = self.tool_prompt_node >> self.router_node
 
-        # Add connections from ports of router to function nodes and back to router
         for function_name, FunctionNodeClass in self._function_nodes.items():
-            router_port = getattr(self.tool_router_node.Ports, function_name)
-            edge_graph = router_port >> FunctionNodeClass >> self.tool_router_node
-            graph_set.add(edge_graph)
-
-        else_node = create_else_node(self.tool_router_node)
-        default_port = self.tool_router_node.Ports.default >> {
-            else_node.Ports.loop >> self.tool_router_node,
-            else_node.Ports.end,
+            router_port = getattr(self.router_node.Ports, function_name)
+            function_subgraph = router_port >> FunctionNodeClass >> self.router_node
+            graph._extend_edges(function_subgraph.edges)
+
+        else_node = create_else_node(self.tool_prompt_node)
+        default_port_graph = self.router_node.Ports.default >> {
+            else_node.Ports.loop_to_router >> self.router_node,  # More outputs to process
+            else_node.Ports.loop_to_prompt >> self.tool_prompt_node,  # Need new prompt iteration
+            else_node.Ports.end,  # Finished
         }
-        graph_set.add(default_port)
+        graph._extend_edges(default_port_graph.edges)
 
-        self._graph = Graph.from_set(graph_set)
+        self._graph = graph

vellum/workflows/nodes/displayable/tool_calling_node/tests/test_node.py

@@ -16,7 +16,11 @@ from vellum.workflows.inputs.base import BaseInputs
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.nodes.displayable.tool_calling_node.node import ToolCallingNode
 from vellum.workflows.nodes.displayable.tool_calling_node.state import ToolCallingState
-from vellum.workflows.nodes.displayable.tool_calling_node.utils import create_function_node, create_tool_router_node
+from vellum.workflows.nodes.displayable.tool_calling_node.utils import (
+    create_function_node,
+    create_router_node,
+    create_tool_prompt_node,
+)
 from vellum.workflows.outputs.base import BaseOutputs
 from vellum.workflows.state.base import BaseState, StateMeta
 from vellum.workflows.state.context import WorkflowContext
@@ -35,8 +39,8 @@ def test_port_condition_match_function_name():
     """
     Test that the port condition correctly matches the function name.
     """
-    # GIVEN a tool router node
-    router_node = create_tool_router_node(
+    # GIVEN a tool prompt node
+    tool_prompt_node = create_tool_prompt_node(
         ml_model="test-model",
         blocks=[],
         functions=[first_function, second_function],
@@ -44,11 +48,17 @@ def test_port_condition_match_function_name():
         parameters=DEFAULT_PROMPT_PARAMETERS,
     )
 
+    # AND a router node that references the tool prompt node
+    router_node = create_router_node(
+        functions=[first_function, second_function],
+        tool_prompt_node=tool_prompt_node,
+    )
+
     # AND a state with a function call to the first function
     state = ToolCallingState(
         meta=StateMeta(
             node_outputs={
-                router_node.Outputs.results: [
+                tool_prompt_node.Outputs.results: [
                     FunctionCallVellumValue(
                         value=FunctionCall(
                             arguments={}, id="call_zp7pBQjGAOBCr7lo0AbR1HXT", name="first_function", state="FULFILLED"
@@ -93,8 +103,8 @@ def test_tool_calling_node_inline_workflow_context():
         class Outputs(BaseOutputs):
             generated_files = MyNode.Outputs.generated_files
 
-    # GIVEN a tool router node
-    tool_router_node = create_tool_router_node(
+    # GIVEN a tool prompt node
+    tool_prompt_node = create_tool_prompt_node(
         ml_model="test-model",
         blocks=[],
         functions=[MyWorkflow],
@@ -105,7 +115,7 @@ def test_tool_calling_node_inline_workflow_context():
     # WHEN we create a function node for the workflow
     function_node_class = create_function_node(
         function=MyWorkflow,
-        tool_router_node=tool_router_node,
+        tool_prompt_node=tool_prompt_node,
     )
 
     # AND we create an instance with a context containing generated_files

vellum/workflows/nodes/displayable/tool_calling_node/tests/test_utils.py

@@ -13,7 +13,7 @@ from vellum.workflows import BaseWorkflow
 from vellum.workflows.inputs.base import BaseInputs
 from vellum.workflows.nodes.bases import BaseNode
 from vellum.workflows.nodes.displayable.tool_calling_node.utils import (
-    create_tool_router_node,
+    create_tool_prompt_node,
     get_function_name,
     get_mcp_tool_name,
 )
@@ -104,9 +104,9 @@ def test_get_function_name_composio_tool_definition_various_toolkits(
     assert result == expected_result
 
 
-def test_create_tool_router_node_max_prompt_iterations(vellum_adhoc_prompt_client):
+def test_create_tool_prompt_node_max_prompt_iterations(vellum_adhoc_prompt_client):
     # GIVEN a tool router node with max_prompt_iterations set to None
-    tool_router_node = create_tool_router_node(
+    tool_prompt_node = create_tool_prompt_node(
         ml_model="gpt-4o-mini",
         blocks=[],
         functions=[],
@@ -129,7 +129,7 @@ def test_create_tool_router_node_max_prompt_iterations(vellum_adhoc_prompt_clien
     vellum_adhoc_prompt_client.adhoc_execute_prompt_stream.side_effect = generate_prompt_events
 
     # WHEN we run the tool router node
-    node_instance = tool_router_node()
+    node_instance = tool_prompt_node()
     outputs = list(node_instance.run())
     assert outputs[0].name == "results"
     assert outputs[0].value == [StringVellumValue(type="STRING", value="test output")]
@@ -137,7 +137,7 @@ def test_create_tool_router_node_max_prompt_iterations(vellum_adhoc_prompt_clien
     assert outputs[1].value == "test output"
 
 
-def test_create_tool_router_node_chat_history_block_dict(vellum_adhoc_prompt_client):
+def test_create_tool_prompt_node_chat_history_block_dict(vellum_adhoc_prompt_client):
     # GIVEN a list of blocks with a chat history block
     blocks = [
         {
@@ -165,7 +165,7 @@ def test_create_tool_router_node_chat_history_block_dict(vellum_adhoc_prompt_cli
         },
     ]
 
-    tool_router_node = create_tool_router_node(
+    tool_prompt_node = create_tool_prompt_node(
         ml_model="gpt-4o-mini",
         blocks=blocks,  # type: ignore
         functions=[],
@@ -187,7 +187,7 @@ def test_create_tool_router_node_chat_history_block_dict(vellum_adhoc_prompt_cli
     vellum_adhoc_prompt_client.adhoc_execute_prompt_stream.side_effect = generate_prompt_events
 
     # WHEN we run the tool router node
-    node_instance = tool_router_node()
+    node_instance = tool_prompt_node()
     list(node_instance.run())
 
     # THEN the API was called with compiled blocks