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

vellum/workflows/graph/graph.py

@@ -1,48 +1,80 @@
-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
 
 from vellum.workflows.edges.edge import Edge
+from vellum.workflows.edges.trigger_edge import TriggerEdge
 from vellum.workflows.types.generics import NodeType
 
 if TYPE_CHECKING:
     from vellum.workflows.nodes.bases.base import BaseNode
     from vellum.workflows.ports.port import Port
+    from vellum.workflows.triggers.base import BaseTrigger
+
+
+class NoPortsNode:
+    """Wrapper for nodes that have no ports defined."""
+
+    def __init__(self, node_class: Type["BaseNode"]):
+        self.node_class = node_class
+
+    def __repr__(self) -> str:
+        return self.node_class.__name__
+
+    def __rshift__(self, other: "GraphTarget") -> "Graph":
+        raise ValueError(
+            f"Cannot create edges from {self.node_class.__name__} because it has no ports defined. "
+            f"Nodes with empty Ports classes cannot be connected to other nodes."
+        )
+
 
 GraphTargetOfSets = Union[
     Set[NodeType],
     Set["Graph"],
     Set["Port"],
-    Set[Union[Type["BaseNode"], "Graph", "Port"]],
+    Set[Union[Type["BaseNode"], "Graph", "Port", "NoPortsNode"]],
 ]
 
 GraphTarget = Union[
     Type["BaseNode"],
     "Port",
     "Graph",
+    "NoPortsNode",
     GraphTargetOfSets,
 ]
 
 
 class Graph:
-    _entrypoints: Set["Port"]
+    _entrypoints: Set[Union["Port", "NoPortsNode"]]
     _edges: List[Edge]
-    _terminals: Set["Port"]
+    _terminals: Set[Union["Port", "NoPortsNode"]]
+    _trigger_edges: List[TriggerEdge]
 
-    def __init__(self, entrypoints: Set["Port"], edges: List[Edge], terminals: Set["Port"]):
+    def __init__(
+        self,
+        entrypoints: Set[Union["Port", "NoPortsNode"]],
+        edges: List[Edge],
+        terminals: Set[Union["Port", "NoPortsNode"]],
+        trigger_edges: Optional[List[TriggerEdge]] = None,
+    ):
         self._edges = edges
         self._entrypoints = entrypoints
         self._terminals = terminals
+        self._trigger_edges = trigger_edges or []
 
     @staticmethod
     def from_port(port: "Port") -> "Graph":
-        ports = {port}
+        ports: Set[Union["Port", "NoPortsNode"]] = {port}
         return Graph(entrypoints=ports, edges=[], terminals=ports)
 
     @staticmethod
     def from_node(node: Type["BaseNode"]) -> "Graph":
         ports = {port for port in node.Ports}
-        return Graph(entrypoints=ports, edges=[], terminals=ports)
+        if not ports:
+            no_ports_node = NoPortsNode(node)
+            return Graph(entrypoints={no_ports_node}, edges=[], terminals={no_ports_node})
+        ports_set: Set[Union["Port", "NoPortsNode"]] = set(ports)
+        return Graph(entrypoints=ports_set, edges=[], terminals=ports_set)
 
     @staticmethod
     def from_set(targets: GraphTargetOfSets) -> "Graph":
@@ -69,14 +101,98 @@ class Graph:
     def from_edge(edge: Edge) -> "Graph":
         return Graph(entrypoints={edge.from_port}, edges=[edge], terminals={port for port in edge.to_node.Ports})
 
+    @staticmethod
+    def from_trigger_edge(edge: TriggerEdge) -> "Graph":
+        """
+        Create a graph from a single TriggerEdge (Trigger >> Node).
+
+        Args:
+            edge: TriggerEdge connecting a trigger to a node
+
+        Returns:
+            Graph with the trigger edge and the target node's ports as terminals
+        """
+        ports = {port for port in edge.to_node.Ports}
+        if not ports:
+            no_ports_node = NoPortsNode(edge.to_node)
+            return Graph(
+                entrypoints={no_ports_node},
+                edges=[],
+                terminals={no_ports_node},
+                trigger_edges=[edge],
+            )
+        return Graph(
+            entrypoints=set(ports),
+            edges=[],
+            terminals=set(ports),
+            trigger_edges=[edge],
+        )
+
+    @staticmethod
+    def from_trigger_edges(edges: List[TriggerEdge]) -> "Graph":
+        """
+        Create a graph from multiple TriggerEdges (e.g., Trigger >> {NodeA, NodeB}).
+
+        Args:
+            edges: List of TriggerEdges
+
+        Returns:
+            Graph with all trigger edges and target nodes' ports as entrypoints/terminals
+        """
+        entrypoints: Set[Union["Port", NoPortsNode]] = set()
+        terminals: Set[Union["Port", NoPortsNode]] = set()
+
+        for edge in edges:
+            ports = {port for port in edge.to_node.Ports}
+            if not ports:
+                no_ports_node = NoPortsNode(edge.to_node)
+                entrypoints.add(no_ports_node)
+                terminals.add(no_ports_node)
+            else:
+                entrypoints.update(ports)
+                terminals.update(ports)
+
+        return Graph(
+            entrypoints=entrypoints,
+            edges=[],
+            terminals=terminals,
+            trigger_edges=edges,
+        )
+
+    @staticmethod
+    def empty() -> "Graph":
+        """Create an empty graph with no entrypoints, edges, or terminals."""
+        return Graph(entrypoints=set(), edges=[], terminals=set())
+
     def __rshift__(self, other: GraphTarget) -> "Graph":
+        # Check for trigger target (class-level only)
+        from vellum.workflows.triggers.base import BaseTrigger
+
+        if isinstance(other, type) and issubclass(other, BaseTrigger):
+            raise TypeError(
+                f"Cannot create edge targeting trigger {other.__name__}. "
+                f"Triggers must be at the start of a graph path, not as targets."
+            )
+
         if not self._edges and not self._entrypoints:
-            raise ValueError("Graph instance can only create new edges from nodes within existing edges")
+            raise ValueError(
+                "Cannot create edges from nodes with empty Ports classes (like TERMINAL/FinalOutputNode). "
+                "TERMINAL nodes are designed to be workflow outputs and cannot connect to other nodes."
+            )
+
+        if self._terminals and all(isinstance(terminal, NoPortsNode) for terminal in self._terminals):
+            terminal_names = [terminal.node_class.__name__ for terminal in self._terminals]
+            raise ValueError(
+                f"Cannot create edges from graph because all terminal nodes have no ports defined: "
+                f"{', '.join(terminal_names)}. Nodes with empty Ports classes cannot be connected to other nodes."
+            )
 
         if isinstance(other, set):
             new_terminals = set()
             for elem in other:
                 for final_output_node in self._terminals:
+                    if isinstance(final_output_node, NoPortsNode):
+                        continue
                     if isinstance(elem, Graph):
                         midgraph = final_output_node >> set(elem.entrypoints)
                         self._extend_edges(midgraph.edges)
@@ -98,6 +214,8 @@ class Graph:
 
         if isinstance(other, Graph):
             for final_output_node in self._terminals:
+                if isinstance(final_output_node, NoPortsNode):
+                    continue
                 midgraph = final_output_node >> set(other.entrypoints)
                 self._extend_edges(midgraph.edges)
                 self._extend_edges(other.edges)
@@ -106,6 +224,8 @@ class Graph:
 
         if hasattr(other, "Ports"):
             for final_output_node in self._terminals:
+                if isinstance(final_output_node, NoPortsNode):
+                    continue
                 subgraph = final_output_node >> other
                 self._extend_edges(subgraph.edges)
             self._terminals = {port for port in other.Ports}
@@ -113,6 +233,8 @@ class Graph:
 
         # other is a Port
         for final_output_node in self._terminals:
+            if isinstance(final_output_node, NoPortsNode):
+                continue
             subgraph = final_output_node >> other
             self._extend_edges(subgraph.edges)
         self._terminals = {other}
@@ -132,9 +254,30 @@ class Graph:
     def edges(self) -> Iterator[Edge]:
         return iter(self._edges)
 
+    @property
+    def trigger_edges(self) -> Iterator[TriggerEdge]:
+        """Get all trigger edges in this graph."""
+        return iter(self._trigger_edges)
+
+    @property
+    def triggers(self) -> Iterator[Type["BaseTrigger"]]:
+        """Get all unique trigger classes in this graph."""
+        seen_triggers = set()
+        for trigger_edge in self._trigger_edges:
+            if trigger_edge.trigger_class not in seen_triggers:
+                seen_triggers.add(trigger_edge.trigger_class)
+                yield trigger_edge.trigger_class
+
     @property
     def nodes(self) -> Iterator[Type["BaseNode"]]:
         nodes = set()
+
+        # Include nodes from trigger edges
+        for trigger_edge in self._trigger_edges:
+            if trigger_edge.to_node not in nodes:
+                nodes.add(trigger_edge.to_node)
+                yield trigger_edge.to_node
+
         if not self._edges:
             for node in self.entrypoints:
                 if node not in nodes:
@@ -154,3 +297,107 @@ 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: Union["Port", "NoPortsNode"]) -> str:
+        """Get a readable name for a port."""
+        if isinstance(port, NoPortsNode):
+            return f"{port.node_class.__name__} (no ports)"
+        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

@@ -1,7 +1,27 @@
+import pytest
+
 from vellum.workflows.edges.edge import Edge
 from vellum.workflows.graph.graph import Graph
 from vellum.workflows.nodes.bases.base import BaseNode
 from vellum.workflows.ports.port import Port
+from vellum.workflows.triggers import ManualTrigger
+
+
+def test_graph__empty():
+    # WHEN we create an empty graph
+    graph = Graph.empty()
+
+    # THEN the graph has no entrypoints
+    assert len(list(graph.entrypoints)) == 0
+
+    # AND no nodes
+    assert len(list(graph.nodes)) == 0
+
+    # AND no edges
+    assert len(list(graph.edges)) == 0
+
+    # AND string representation indicates empty graph
+    assert str(graph) == "Graph(empty)"
 
 
 def test_graph__from_node():
@@ -484,3 +504,283 @@ 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
+
+
+def test_graph__from_node_with_empty_ports():
+    """
+    Tests that building a graph from a single node with empty Ports class generates 1 node.
+    """
+
+    # GIVEN a node with an empty Ports class
+    class NodeWithEmptyPorts(BaseNode):
+        class Ports(BaseNode.Ports):
+            pass
+
+    # WHEN we create a graph from the node
+    graph = Graph.from_node(NodeWithEmptyPorts)
+
+    # THEN the graph should have exactly 1 node
+    assert len(list(graph.nodes)) == 1
+
+
+def test_graph__manual_trigger_to_node():
+    # GIVEN a node
+    class MyNode(BaseNode):
+        pass
+
+    # WHEN we create graph with ManualTrigger >> Node (class-level, no instantiation)
+    graph = ManualTrigger >> MyNode
+
+    # THEN the graph has one trigger edge
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 1
+    assert trigger_edges[0].trigger_class == ManualTrigger
+    assert trigger_edges[0].to_node == MyNode
+
+    # AND the graph has one trigger
+    triggers = list(graph.triggers)
+    assert len(triggers) == 1
+    assert triggers[0] == ManualTrigger
+
+    # AND the graph has one node
+    assert len(list(graph.nodes)) == 1
+    assert MyNode in list(graph.nodes)
+
+
+def test_graph__manual_trigger_to_set_of_nodes():
+    # GIVEN two nodes
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    # WHEN we create graph with ManualTrigger >> {NodeA, NodeB}
+    graph = ManualTrigger >> {NodeA, NodeB}
+
+    # THEN the graph has two trigger edges
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 2
+
+    # AND both edges connect to the same ManualTrigger class
+    assert all(edge.trigger_class == ManualTrigger for edge in trigger_edges)
+
+    # AND edges connect to both nodes
+    target_nodes = {edge.to_node for edge in trigger_edges}
+    assert target_nodes == {NodeA, NodeB}
+
+    # AND the graph has one unique trigger
+    triggers = list(graph.triggers)
+    assert len(triggers) == 1
+
+    # AND the graph has two nodes
+    assert len(list(graph.nodes)) == 2
+
+
+def test_graph__manual_trigger_to_graph():
+    # GIVEN a graph of nodes
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    node_graph = NodeA >> NodeB
+
+    # WHEN we create graph with ManualTrigger >> Graph
+    graph = ManualTrigger >> node_graph
+
+    # THEN the graph has a trigger edge to the entrypoint
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 1
+    assert trigger_edges[0].to_node == NodeA
+
+    # AND the graph preserves the original edges
+    edges = list(graph.edges)
+    assert len(edges) == 1
+    assert edges[0].to_node == NodeB
+
+    # AND the graph has both nodes
+    nodes = list(graph.nodes)
+    assert len(nodes) == 2
+    assert NodeA in nodes
+    assert NodeB in nodes
+
+
+def test_graph__manual_trigger_to_set_of_graphs_preserves_edges():
+    # GIVEN two graphs of nodes
+    class NodeA(BaseNode):
+        pass
+
+    class NodeB(BaseNode):
+        pass
+
+    class NodeC(BaseNode):
+        pass
+
+    class NodeD(BaseNode):
+        pass
+
+    graph_one = NodeA >> NodeB
+    graph_two = NodeC >> NodeD
+
+    # WHEN we create a graph with ManualTrigger >> {Graph1, Graph2}
+    combined_graph = ManualTrigger >> {graph_one, graph_two}
+
+    # THEN the combined graph has trigger edges to both entrypoints
+    trigger_edges = list(combined_graph.trigger_edges)
+    assert len(trigger_edges) == 2
+    assert {edge.to_node for edge in trigger_edges} == {NodeA, NodeC}
+
+    # AND the combined graph preserves all downstream edges
+    edges = list(combined_graph.edges)
+    assert len(edges) == 2
+    assert {(edge.from_port.node_class, edge.to_node) for edge in edges} == {
+        (NodeA, NodeB),
+        (NodeC, NodeD),
+    }
+
+    # AND the combined graph still exposes all nodes
+    nodes = list(combined_graph.nodes)
+    assert {NodeA, NodeB, NodeC, NodeD}.issubset(nodes)
+
+
+def test_graph__node_to_trigger_raises():
+    # GIVEN a node and trigger
+    class MyNode(BaseNode):
+        pass
+
+    # WHEN we try to create Node >> Trigger (class-level)
+    # THEN it raises TypeError
+    with pytest.raises(TypeError, match="Cannot create edge targeting trigger"):
+        MyNode >> ManualTrigger
+
+    # WHEN we try to create Node >> Trigger (instance-level)
+    # THEN it also raises TypeError
+    with pytest.raises(TypeError, match="Cannot create edge targeting trigger"):
+        MyNode >> ManualTrigger
+
+
+def test_graph__trigger_then_graph_then_node():
+    # GIVEN a trigger, a node, and another node
+    class StartNode(BaseNode):
+        pass
+
+    class EndNode(BaseNode):
+        pass
+
+    # WHEN we create Trigger >> Node >> Node
+    graph = ManualTrigger >> StartNode >> EndNode
+
+    # THEN the graph has one trigger edge
+    trigger_edges = list(graph.trigger_edges)
+    assert len(trigger_edges) == 1
+    assert trigger_edges[0].to_node == StartNode
+
+    # AND the graph has one regular edge
+    edges = list(graph.edges)
+    assert len(edges) == 1
+    assert edges[0].to_node == EndNode
+
+    # AND the graph has both nodes
+    nodes = list(graph.nodes)
+    assert len(nodes) == 2

vellum/workflows/inputs/__init__.py

@@ -1,5 +1,7 @@
 from .base import BaseInputs
+from .dataset_row import DatasetRow
 
 __all__ = [
     "BaseInputs",
+    "DatasetRow",
 ]