vellum-ai 0.9.16rc2__py3-none-any.whl → 0.9.16rc4__py3-none-any.whl

vellum/workflows/README.md

@@ -0,0 +1,90 @@
+<p align="center">
+  <h1 align="center">
+  Vellum Workflows SDK
+  </h1>
+  <p align="center">
+    <a href="https://docs.vellum.ai/developers/workflows-sdk">Learn more</a>
+    ·
+    <a href="https://www.vellum.ai/landing-pages/request-demo">Talk to us</a>
+  </p>
+</p>
+
+# Introduction
+
+The Vellum Workflows SDK is a framework for defining and executing complex AI systems as graphs.
+
+The Vellum Workflows SDK provides a declarative python syntax for both defining and executing the control flow of graphs.
+Unlike other graph execution frameworks, which are functional or event-driven in nature, Vellum's Workflows SDK defines the control flow of a graph
+statically and makes use of strict typing. This means that the structure of the graph is known ahead of time, and you get all the benefits of type
+safety and intellisense. This ultimately makes it easier to build more predictable and robust AI systems.
+
+Unique amongst other frameworks, Vellum's Workflows SDK also allows you to _visualize, edit, and execute_ your graph in a UI, pushing and pulling changes from
+code to UI and vice versa.
+
+
+## Core Features
+- **Nodes**: Nodes are the basic building blocks of a graph. They represent a single task or function that can be executed.
+- **Graph Syntax**: An intuitive declarative syntax for defining the control flow of a graph.
+- **Inputs and Outputs**: Both the Workflow itslef and individual Nodes can take in inputs and produce outputs, which can be used to pass information between nodes.
+- **State**: Nodes can read and write to the graph's global state, which can be used to share information between nodes without defining explicit inputs and outputs.
+- **Advanced Control Flow**: Support for looping, conditionals, paralellism, state forking, and more.
+- **Streaming**: Nodes can stream output values back to the runner, allowing for long-running tasks like chat completions to return partial results.
+- **Human-in-the-loop**: Nodes can wait for External Inputs, allowing for a pause in the Workflow until a human or external system provides input.
+- **UI Integration**: Push and pull changes from code to Vellum's UI and vice versa, allowing for rapid testing and iteration.
+
+## Quickstart
+
+1. Install the Vellum Workflows SDK:
+
+    ```bash
+    pip install vellum-ai
+    ```
+
+2. Import the Vellum Workflows SDK and define your first Workflow:
+
+    ```python
+    # my_workflow.py
+
+    from workflows import BaseWorkflow
+    from workflows.nodes import BaseNode
+
+
+    class MyNode(BaseNode):
+
+        class Outputs(BaseNode.Outputs):
+            result: str
+
+        def run(self):
+            return self.Outputs(result="Hello, World!")
+
+
+    class MyWorkflow(BaseWorkflow):
+        graph = MyNode
+
+        class Outputs(BaseWorkflow.Outputs):
+            result = MyNode.Outputs.result
+
+
+    if __name__ == "__main__":
+        workflow = MyWorkflow()
+        result = workflow.run()
+
+        print(result.outputs.result)
+
+    ```
+3. Run it!
+
+    ```bash
+    python my_workflow.py
+
+Note: To use most out-of-box Nodes, and to push/pull to/from the Velłum UI, you'll need a Vellum account and API key. [Talk to us](https://www.vellum.ai/landing-pages/request-demo) or visit our [pricing page](https://www.vellum.ai/pricing) for more information.
+
+
+## Documentation
+Complete documentation for the Vellum Workflows SDK can be found at https://docs.vellum.ai/developers/workflows-sdk.
+
+
+## Stability
+
+This SDK is currently in <Availability type="beta" /> and is subject to change. If you'd like to pariticpate in
+our beta program, please [contact us](https://docs.vellum.ai/home/getting-started/support).

vellum/workflows/__init__.py

@@ -0,0 +1,5 @@
+from .workflows import BaseWorkflow
+
+__all__ = [
+    "BaseWorkflow",
+]

vellum/workflows/constants.py

@@ -0,0 +1,43 @@
+from enum import Enum
+from typing import Any, cast
+
+
+class _UndefMeta(type):
+    def __repr__(cls) -> str:
+        return "UNDEF"
+
+    def __getattribute__(cls, name: str) -> Any:
+        if name == "__class__":
+            # ensures that UNDEF.__class__ == UNDEF
+            return cls
+
+        return super().__getattribute__(name)
+
+    def __bool__(cls) -> bool:
+        return False
+
+
+class UNDEF(metaclass=_UndefMeta):
+    pass
+
+
+LATEST_RELEASE_TAG = "LATEST"
+
+OMIT = cast(Any, ...)
+
+
+class APIRequestMethod(Enum):
+    GET = "GET"
+    POST = "POST"
+    PUT = "PUT"
+    DELETE = "DELETE"
+    PATCH = "PATCH"
+    OPTIONS = "OPTIONS"
+    HEAD = "HEAD"
+    CONNECT = "CONNECT"
+    TRACE = "TRACE"
+
+
+class AuthorizationType(Enum):
+    BEARER_TOKEN = "BEARER_TOKEN"
+    API_KEY = "API_KEY"

vellum/workflows/descriptors/base.py

@@ -0,0 +1,339 @@
+from typing import TYPE_CHECKING, Any, Generic, Optional, Tuple, Type, TypeVar, Union, cast, overload
+
+if TYPE_CHECKING:
+    from vellum.workflows.expressions.accessor import AccessorExpression
+    from vellum.workflows.expressions.and_ import AndExpression
+    from vellum.workflows.expressions.begins_with import BeginsWithExpression
+    from vellum.workflows.expressions.between import BetweenExpression
+    from vellum.workflows.expressions.coalesce_expression import CoalesceExpression
+    from vellum.workflows.expressions.contains import ContainsExpression
+    from vellum.workflows.expressions.does_not_begin_with import DoesNotBeginWithExpression
+    from vellum.workflows.expressions.does_not_contain import DoesNotContainExpression
+    from vellum.workflows.expressions.does_not_end_with import DoesNotEndWithExpression
+    from vellum.workflows.expressions.does_not_equal import DoesNotEqualExpression
+    from vellum.workflows.expressions.ends_with import EndsWithExpression
+    from vellum.workflows.expressions.equals import EqualsExpression
+    from vellum.workflows.expressions.greater_than import GreaterThanExpression
+    from vellum.workflows.expressions.greater_than_or_equal_to import GreaterThanOrEqualToExpression
+    from vellum.workflows.expressions.in_ import InExpression
+    from vellum.workflows.expressions.is_blank import IsBlankExpression
+    from vellum.workflows.expressions.is_not_blank import IsNotBlankExpression
+    from vellum.workflows.expressions.is_not_null import IsNotNullExpression
+    from vellum.workflows.expressions.is_not_undefined import IsNotUndefinedExpression
+    from vellum.workflows.expressions.is_null import IsNullExpression
+    from vellum.workflows.expressions.is_undefined import IsUndefinedExpression
+    from vellum.workflows.expressions.less_than import LessThanExpression
+    from vellum.workflows.expressions.less_than_or_equal_to import LessThanOrEqualToExpression
+    from vellum.workflows.expressions.not_between import NotBetweenExpression
+    from vellum.workflows.expressions.not_in import NotInExpression
+    from vellum.workflows.expressions.or_ import OrExpression
+    from vellum.workflows.nodes.bases import BaseNode
+    from vellum.workflows.state.base import BaseState
+
+_T = TypeVar("_T")
+_O = TypeVar("_O")
+_O2 = TypeVar("_O2")
+
+
+class BaseDescriptor(Generic[_T]):
+    _name: str
+    _types: Tuple[Type[_T], ...]
+    _instance: Optional[_T]
+
+    def __init__(self, *, name: str, types: Tuple[Type[_T], ...], instance: Optional[_T] = None) -> None:
+        self._name = name
+        self._types = types
+        self._instance = instance
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def types(self) -> Tuple[Type[_T], ...]:
+        return self._types
+
+    @property
+    def instance(self) -> Optional[_T]:
+        return self._instance
+
+    def resolve(self, state: "BaseState") -> _T:
+        raise NotImplementedError("Descriptor must implement resolve method")
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, type(self)):
+            return False
+        return self._name == other._name
+
+    def __hash__(self) -> int:
+        return hash(self._name)
+
+    @overload
+    def __get__(self, instance: "BaseNode", owner: Type["BaseNode"]) -> _T: ...
+
+    @overload
+    def __get__(self, instance: Any, owner: Optional[Type]) -> "BaseDescriptor[_T]": ...
+
+    def __get__(self, instance: Any, owner: Optional[Type]) -> Union["BaseDescriptor[_T]", _T]:
+        if not instance:
+            return self
+
+        if instance.__class__.__name__ == "BaseNode":
+            node = cast("BaseNode", instance)
+            return self.resolve(node.state)
+
+        return self
+
+    # TODO: We should figure out how to remove these dynamic imports
+    # https://app.shortcut.com/vellum/story/4504
+    @overload
+    def __or__(self, other: "BaseDescriptor[_O]") -> "OrExpression[_T, _O]": ...
+
+    @overload
+    def __or__(self, other: _O) -> "OrExpression[_T, _O]": ...
+
+    def __or__(self, other: "Union[BaseDescriptor[_O], _O]") -> "OrExpression[_T, _O]":
+        from vellum.workflows.expressions.or_ import OrExpression
+
+        return OrExpression(lhs=self, rhs=other)
+
+    @overload
+    def __and__(self, other: "BaseDescriptor[_O]") -> "AndExpression[_T, _O]": ...
+
+    @overload
+    def __and__(self, other: _O) -> "AndExpression[_T, _O]": ...
+
+    def __and__(self, other: "Union[BaseDescriptor[_O], _O]") -> "AndExpression[_T, _O]":
+        from vellum.workflows.expressions.and_ import AndExpression
+
+        return AndExpression(lhs=self, rhs=other)
+
+    @overload
+    def coalesce(self, other: "BaseDescriptor[_O]") -> "CoalesceExpression[_T, _O]": ...
+
+    @overload
+    def coalesce(self, other: _O) -> "CoalesceExpression[_T, _O]": ...
+
+    def coalesce(self, other: "Union[BaseDescriptor[_O], _O]") -> "CoalesceExpression[_T, _O]":
+        from vellum.workflows.expressions.coalesce_expression import CoalesceExpression
+
+        return CoalesceExpression(lhs=self, rhs=other)
+
+    def __getitem__(self, field: str) -> "AccessorExpression":
+        from vellum.workflows.expressions.accessor import AccessorExpression
+
+        return AccessorExpression(base=self, field=field)
+
+    @overload
+    def equals(self, other: "BaseDescriptor[_O]") -> "EqualsExpression[_T, _O]": ...
+
+    @overload
+    def equals(self, other: _O) -> "EqualsExpression[_T, _O]": ...
+
+    def equals(self, other: "Union[BaseDescriptor[_O], _O]") -> "EqualsExpression[_T, _O]":
+        from vellum.workflows.expressions.equals import EqualsExpression
+
+        return EqualsExpression(lhs=self, rhs=other)
+
+    @overload
+    def does_not_equal(self, other: "BaseDescriptor[_O]") -> "DoesNotEqualExpression[_T, _O]": ...
+
+    @overload
+    def does_not_equal(self, other: _O) -> "DoesNotEqualExpression[_T, _O]": ...
+
+    def does_not_equal(self, other: "Union[BaseDescriptor[_O], _O]") -> "DoesNotEqualExpression[_T, _O]":
+        from vellum.workflows.expressions.does_not_equal import DoesNotEqualExpression
+
+        return DoesNotEqualExpression(lhs=self, rhs=other)
+
+    @overload
+    def less_than(self, other: "BaseDescriptor[_O]") -> "LessThanExpression[_T, _O]": ...
+
+    @overload
+    def less_than(self, other: _O) -> "LessThanExpression[_T, _O]": ...
+
+    def less_than(self, other: "Union[BaseDescriptor[_O], _O]") -> "LessThanExpression[_T, _O]":
+        from vellum.workflows.expressions.less_than import LessThanExpression
+
+        return LessThanExpression(lhs=self, rhs=other)
+
+    @overload
+    def greater_than(self, other: "BaseDescriptor[_O]") -> "GreaterThanExpression[_T, _O]": ...
+
+    @overload
+    def greater_than(self, other: _O) -> "GreaterThanExpression[_T, _O]": ...
+
+    def greater_than(self, other: "Union[BaseDescriptor[_O], _O]") -> "GreaterThanExpression[_T, _O]":
+        from vellum.workflows.expressions.greater_than import GreaterThanExpression
+
+        return GreaterThanExpression(lhs=self, rhs=other)
+
+    @overload
+    def less_than_or_equal_to(self, other: "BaseDescriptor[_O]") -> "LessThanOrEqualToExpression[_T, _O]": ...
+
+    @overload
+    def less_than_or_equal_to(self, other: _O) -> "LessThanOrEqualToExpression[_T, _O]": ...
+
+    def less_than_or_equal_to(self, other: "Union[BaseDescriptor[_O], _O]") -> "LessThanOrEqualToExpression[_T, _O]":
+        from vellum.workflows.expressions.less_than_or_equal_to import LessThanOrEqualToExpression
+
+        return LessThanOrEqualToExpression(lhs=self, rhs=other)
+
+    @overload
+    def greater_than_or_equal_to(self, other: "BaseDescriptor[_O]") -> "GreaterThanOrEqualToExpression[_T, _O]": ...
+
+    @overload
+    def greater_than_or_equal_to(self, other: _O) -> "GreaterThanOrEqualToExpression[_T, _O]": ...
+
+    def greater_than_or_equal_to(
+        self, other: "Union[BaseDescriptor[_O], _O]"
+    ) -> "GreaterThanOrEqualToExpression[_T, _O]":
+        from vellum.workflows.expressions.greater_than_or_equal_to import GreaterThanOrEqualToExpression
+
+        return GreaterThanOrEqualToExpression(lhs=self, rhs=other)
+
+    @overload
+    def contains(self, other: "BaseDescriptor[_O]") -> "ContainsExpression[_T, _O]": ...
+
+    @overload
+    def contains(self, other: _O) -> "ContainsExpression[_T, _O]": ...
+
+    def contains(self, other: "Union[BaseDescriptor[_O], _O]") -> "ContainsExpression[_T, _O]":
+        from vellum.workflows.expressions.contains import ContainsExpression
+
+        return ContainsExpression(lhs=self, rhs=other)
+
+    @overload
+    def begins_with(self, other: "BaseDescriptor[_O]") -> "BeginsWithExpression[_T, _O]": ...
+
+    @overload
+    def begins_with(self, other: _O) -> "BeginsWithExpression[_T, _O]": ...
+
+    def begins_with(self, other: "Union[BaseDescriptor[_O], _O]") -> "BeginsWithExpression[_T, _O]":
+        from vellum.workflows.expressions.begins_with import BeginsWithExpression
+
+        return BeginsWithExpression(lhs=self, rhs=other)
+
+    @overload
+    def ends_with(self, other: "BaseDescriptor[_O]") -> "EndsWithExpression[_T, _O]": ...
+
+    @overload
+    def ends_with(self, other: _O) -> "EndsWithExpression[_T, _O]": ...
+
+    def ends_with(self, other: "Union[BaseDescriptor[_O], _O]") -> "EndsWithExpression[_T, _O]":
+        from vellum.workflows.expressions.ends_with import EndsWithExpression
+
+        return EndsWithExpression(lhs=self, rhs=other)
+
+    @overload
+    def does_not_contain(self, other: "BaseDescriptor[_O]") -> "DoesNotContainExpression[_T, _O]": ...
+
+    @overload
+    def does_not_contain(self, other: _O) -> "DoesNotContainExpression[_T, _O]": ...
+
+    def does_not_contain(self, other: "Union[BaseDescriptor[_O], _O]") -> "DoesNotContainExpression[_T, _O]":
+        from vellum.workflows.expressions.does_not_contain import DoesNotContainExpression
+
+        return DoesNotContainExpression(lhs=self, rhs=other)
+
+    @overload
+    def does_not_begin_with(self, other: "BaseDescriptor[_O]") -> "DoesNotBeginWithExpression[_T, _O]": ...
+
+    @overload
+    def does_not_begin_with(self, other: _O) -> "DoesNotBeginWithExpression[_T, _O]": ...
+
+    def does_not_begin_with(self, other: "Union[BaseDescriptor[_O], _O]") -> "DoesNotBeginWithExpression[_T, _O]":
+        from vellum.workflows.expressions.does_not_begin_with import DoesNotBeginWithExpression
+
+        return DoesNotBeginWithExpression(lhs=self, rhs=other)
+
+    @overload
+    def does_not_end_with(self, other: "BaseDescriptor[_O]") -> "DoesNotEndWithExpression[_T, _O]": ...
+
+    @overload
+    def does_not_end_with(self, other: _O) -> "DoesNotEndWithExpression[_T, _O]": ...
+
+    def does_not_end_with(self, other: "Union[BaseDescriptor[_O], _O]") -> "DoesNotEndWithExpression[_T, _O]":
+        from vellum.workflows.expressions.does_not_end_with import DoesNotEndWithExpression
+
+        return DoesNotEndWithExpression(lhs=self, rhs=other)
+
+    def is_none(self) -> "IsNullExpression":
+        from vellum.workflows.expressions.is_null import IsNullExpression
+
+        return IsNullExpression(expression=self)
+
+    def is_not_none(self) -> "IsNotNullExpression":
+        from vellum.workflows.expressions.is_not_null import IsNotNullExpression
+
+        return IsNotNullExpression(expression=self)
+
+    def is_undefined(self) -> "IsUndefinedExpression":
+        from vellum.workflows.expressions.is_undefined import IsUndefinedExpression
+
+        return IsUndefinedExpression(expression=self)
+
+    def is_not_undefined(self) -> "IsNotUndefinedExpression":
+        from vellum.workflows.expressions.is_not_undefined import IsNotUndefinedExpression
+
+        return IsNotUndefinedExpression(expression=self)
+
+    @overload
+    def in_(self, other: "BaseDescriptor[_O]") -> "InExpression[_T, _O]": ...
+
+    @overload
+    def in_(self, other: _O) -> "InExpression[_T, _O]": ...
+
+    def in_(self, other: "Union[BaseDescriptor[_O], _O]") -> "InExpression[_T, _O]":
+        from vellum.workflows.expressions.in_ import InExpression
+
+        return InExpression(lhs=self, rhs=other)
+
+    @overload
+    def not_in(self, other: "BaseDescriptor[_O]") -> "NotInExpression[_T, _O]": ...
+
+    @overload
+    def not_in(self, other: _O) -> "NotInExpression[_T, _O]": ...
+
+    def not_in(self, other: "Union[BaseDescriptor[_O], _O]") -> "NotInExpression[_T, _O]":
+        from vellum.workflows.expressions.not_in import NotInExpression
+
+        return NotInExpression(lhs=self, rhs=other)
+
+    @overload
+    def between(self, start: "BaseDescriptor[_O]", end: "BaseDescriptor[_O2]") -> "BetweenExpression[_T, _O, _O2]": ...
+
+    @overload
+    def between(self, start: _O, end: _O2) -> "BetweenExpression[_T, _O, _O2]": ...
+
+    def between(
+        self, start: "Union[BaseDescriptor[_O], _O]", end: "Union[BaseDescriptor[_O2], _O2]"
+    ) -> "BetweenExpression[_T, _O, _O2]":
+        from vellum.workflows.expressions.between import BetweenExpression
+
+        return BetweenExpression(value=self, start=start, end=end)
+
+    @overload
+    def not_between(
+        self, start: "BaseDescriptor[_O]", end: "BaseDescriptor[_O2]"
+    ) -> "NotBetweenExpression[_T, _O, _O2]": ...
+
+    @overload
+    def not_between(self, start: _O, end: _O2) -> "NotBetweenExpression[_T, _O, _O2]": ...
+
+    def not_between(
+        self, start: "Union[BaseDescriptor[_O], _O]", end: "Union[BaseDescriptor[_O2], _O2]"
+    ) -> "NotBetweenExpression[_T, _O, _O2]":
+        from vellum.workflows.expressions.not_between import NotBetweenExpression
+
+        return NotBetweenExpression(value=self, start=start, end=end)
+
+    def is_blank(self) -> "IsBlankExpression":
+        from vellum.workflows.expressions.is_blank import IsBlankExpression
+
+        return IsBlankExpression(expression=self)
+
+    def is_not_blank(self) -> "IsNotBlankExpression":
+        from vellum.workflows.expressions.is_not_blank import IsNotBlankExpression
+
+        return IsNotBlankExpression(expression=self)

vellum/workflows/descriptors/tests/test_utils.py

@@ -0,0 +1,83 @@
+import pytest
+
+from vellum.workflows.descriptors.utils import resolve_value
+from vellum.workflows.state.base import BaseState
+
+
+class FixtureState(BaseState):
+    alpha = 1
+    beta = 2
+
+    gamma = "hello"
+    delta = "el"
+
+    epsilon = 3
+    zeta = {
+        "foo": "bar",
+    }
+
+
+@pytest.mark.parametrize(
+    ["descriptor", "expected_value"],
+    [
+        (FixtureState.alpha | FixtureState.beta, 1),
+        (FixtureState.alpha & FixtureState.beta, 2),
+        (FixtureState.beta.coalesce(FixtureState.alpha), 2),
+        (FixtureState.alpha.equals(FixtureState.beta), False),
+        (FixtureState.alpha.does_not_equal(FixtureState.beta), True),
+        (FixtureState.alpha.less_than(FixtureState.beta), True),
+        (FixtureState.alpha.greater_than(FixtureState.beta), False),
+        (FixtureState.alpha.less_than_or_equal_to(FixtureState.beta), True),
+        (FixtureState.alpha.greater_than_or_equal_to(FixtureState.beta), False),
+        (FixtureState.gamma.contains(FixtureState.delta), True),
+        (FixtureState.gamma.begins_with(FixtureState.delta), False),
+        (FixtureState.gamma.ends_with(FixtureState.delta), False),
+        (FixtureState.gamma.does_not_contain(FixtureState.delta), False),
+        (FixtureState.gamma.does_not_begin_with(FixtureState.delta), True),
+        (FixtureState.gamma.does_not_end_with(FixtureState.delta), True),
+        (FixtureState.alpha.is_none(), False),
+        (FixtureState.alpha.is_not_none(), True),
+        (FixtureState.delta.in_(FixtureState.gamma), True),
+        (FixtureState.delta.not_in(FixtureState.gamma), False),
+        (FixtureState.alpha.between(FixtureState.beta, FixtureState.epsilon), False),
+        (FixtureState.alpha.not_between(FixtureState.beta, FixtureState.epsilon), True),
+        (FixtureState.delta.is_blank(), False),
+        (FixtureState.delta.is_not_blank(), True),
+        (
+            FixtureState.alpha.equals(FixtureState.alpha)
+            | FixtureState.alpha.equals(FixtureState.beta) & FixtureState.alpha.equals(FixtureState.beta),
+            True,
+        ),
+        (FixtureState.zeta["foo"], "bar"),
+    ],
+    ids=[
+        "or",
+        "and",
+        "coalesce",
+        "eq",
+        "dne",
+        "less_than",
+        "greater_than",
+        "less_than_or_equal_to",
+        "greater_than_or_equal_to",
+        "contains",
+        "begins_with",
+        "ends_with",
+        "does_not_contain",
+        "does_not_begin_with",
+        "does_not_end_with",
+        "is_none",
+        "is_not_none",
+        "in_",
+        "not_in",
+        "between",
+        "not_between",
+        "is_blank",
+        "is_not_blank",
+        "or_and",
+        "accessor",
+    ],
+)
+def test_resolve_value__happy_path(descriptor, expected_value):
+    actual_value = resolve_value(descriptor, FixtureState())
+    assert actual_value == expected_value

vellum/workflows/descriptors/utils.py

@@ -0,0 +1,90 @@
+from collections.abc import Mapping
+import dataclasses
+import inspect
+from typing import Any, Dict, Optional, Sequence, Set, TypeVar, Union, cast, overload
+
+from pydantic import BaseModel
+
+from vellum.workflows.descriptors.base import BaseDescriptor
+from vellum.workflows.state.base import BaseState
+
+_T = TypeVar("_T")
+
+
+@overload
+def resolve_value(
+    value: BaseDescriptor[_T], state: BaseState, path: str = "", memo: Optional[Dict[str, Any]] = None
+) -> _T: ...
+
+
+@overload
+def resolve_value(value: _T, state: BaseState, path: str = "", memo: Optional[Dict[str, Any]] = None) -> _T: ...
+
+
+def resolve_value(
+    value: Union[BaseDescriptor[_T], _T], state: BaseState, path: str = "", memo: Optional[Dict[str, Any]] = None
+) -> _T:
+    """
+    Recursively resolves Descriptor's until we have a constant value, using BaseState.
+
+    The nonideal casts in this method are due to the `isinstance` calls detaching types
+    from the `_T` generic.
+    """
+
+    if inspect.isclass(value):
+        return cast(_T, value)
+
+    if isinstance(value, BaseDescriptor):
+        resolved_value = value.resolve(state)
+        if memo is not None:
+            memo[path] = resolved_value
+        return resolved_value
+
+    if isinstance(value, property) or callable(value):
+        return cast(_T, value)
+
+    if isinstance(value, (str, bytes)):
+        return cast(_T, value)
+
+    if dataclasses.is_dataclass(value):
+        # The `inspect.isclass` check above prevents `value` from being a class.
+        dataclass_value = dataclasses.replace(  # type: ignore[type-var]
+            value,
+            **{
+                field.name: resolve_value(getattr(value, field.name), state, path=f"{path}.{field.name}", memo=memo)
+                for field in dataclasses.fields(value)
+            },
+        )
+        return cast(_T, dataclass_value)
+
+    if isinstance(value, BaseModel):
+        pydantic_value = value.model_copy(
+            update={
+                key: resolve_value(getattr(value, key), state, path=f"{path}.{key}", memo=memo)
+                for key in value.dict().keys()
+            }
+        )
+        return cast(_T, pydantic_value)
+
+    if isinstance(value, Mapping):
+        mapped_value = type(value)(  # type: ignore[call-arg]
+            {
+                dict_key: resolve_value(dict_value, state, path=f"{path}.{dict_key}", memo=memo)
+                for dict_key, dict_value in value.items()
+            }
+        )
+        return cast(_T, mapped_value)
+
+    if isinstance(value, Sequence):
+        sequence_value = type(value)(
+            resolve_value(seq_value, state, path=f"{path}.{index}", memo=memo) for index, seq_value in enumerate(value)
+        )  # type: ignore[call-arg]
+        return cast(_T, sequence_value)
+
+    if isinstance(value, Set):
+        set_value = type(value)(
+            resolve_value(set_value, state, path=f"{path}.{index}", memo=memo) for index, set_value in enumerate(value)
+        )
+        return cast(_T, set_value)
+
+    return value

vellum/workflows/edges/__init__.py

@@ -0,0 +1,5 @@
+from .edge import Edge
+
+__all__ = [
+    "Edge",
+]

vellum/workflows/edges/edge.py

@@ -0,0 +1,23 @@
+from typing import TYPE_CHECKING, Any, Type
+
+if TYPE_CHECKING:
+    from vellum.workflows.nodes.bases import BaseNode
+    from vellum.workflows.ports.port import Port
+
+
+class Edge:
+    def __init__(self, from_port: "Port", to_node: Type["BaseNode"]):
+        self.from_port = from_port
+        self.to_node = to_node
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, Edge):
+            return False
+
+        return self.from_port == other.from_port and self.to_node == other.to_node
+
+    def __hash__(self) -> int:
+        return hash((self.from_port, self.to_node))
+
+    def __repr__(self) -> str:
+        return f"{self.from_port} >> {self.to_node}"