vellum-ai 0.9.16rc2__tar.gz → 0.10.0__tar.gz

vellum_ai-0.10.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.1
+Name: vellum-ai
+Version: 0.10.0
+Summary: 
+License: MIT
+Requires-Python: >=3.9,<4.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: Jinja2 (==3.1.2)
+Requires-Dist: cdktf (>=0.20.5,<0.21.0)
+Requires-Dist: click (==8.1.7)
+Requires-Dist: docker (==7.1.0)
+Requires-Dist: httpx (>=0.21.2)
+Requires-Dist: orderly-set (>=5.2.2,<6.0.0)
+Requires-Dist: publication (==0.0.3)
+Requires-Dist: pydantic (>=1.9.2)
+Requires-Dist: pydantic-core (>=2.18.2,<3.0.0)
+Requires-Dist: pydash (==7.0.6)
+Requires-Dist: python-dotenv (==1.0.1)
+Requires-Dist: pytz (==2022.6)
+Requires-Dist: pyyaml (==6.0.1)
+Requires-Dist: requests (==2.32.3)
+Requires-Dist: tomli (==2.0.2)
+Requires-Dist: typing_extensions (>=4.0.0)
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <h1 align="center">
+  Vellum
+  </h1>
+  <p align="center">
+    <a href="https://vellum.ai">Learn more</a>
+    ·
+    <a href="https://www.vellum.ai/landing-pages/request-demo">Talk to us</a>
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://pepy.tech/project/vellum-ai">
+    <img src="https://img.shields.io/pypi/dm/vellum-ai" alt="Vellum AI PyPI - Downloads" >
+  </a>
+  <a href="https://pypi.org/project/vellum-ai" target="_blank">
+    <img src="https://img.shields.io/pypi/v/vellum-ai?color=%2334D058&label=pypi%20package" alt="Package version">
+  </a>
+  <a href="https://www.ycombinator.com/companies/vellum">
+    <img src="https://img.shields.io/badge/Y%20Combinator-W23-orange?style=flat-square" alt="Y Combinator S24">
+  </a>
+</p>
+
+# Introduction
+
+
+[Vellum](https://www.vellum.ai/) is the end-to-end development platform for building production-grade AI applications
+
+### Core Features
+
+- **Orchestration:** A powerful SDK and IDE for defining and debugging the control flow of your AI applications
+- **Prompting:** A best-in-class prompt playground for iterating on and refining prompts between models from any provider
+- **Evaluations**: An evaluations framework that makes it easy to measure the quality of your AI systems at scale.
+- **Retrieval:** A ready-to-go service for turning unstructured content into intelligent, context-aware solutions
+  optimized for AI systems
+- **Deployment:** Decouple updates to your AI systems from your application code with an easy integration +
+  one-click deploy
+- **Observability:** Monitor and debug your AI systems in real-time with detailed logs, metrics, and end-user feedback
+
+## Table of Contents
+
+- [Get Started](#get-started)
+- [Client SDK](#client-sdk)
+- [Workflows SDK](#workflows-sdk)
+- [Contributing](#contributing)
+- [Open-source vs paid](#open-source-vs-paid)
+
+
+## Get Started
+Most functionality within the SDKs here requires a Vellum account and API key. To sign up, [talk to us](https://www.vellum.ai/landing-pages/request-demo)
+or visit our [pricing page](https://www.vellum.ai/pricing).
+
+Even without a Vellum account, you can use the Workflows SDK to define the control flow of your AI systems. [Learn
+more below](#workflows-sdk).
+
+
+
+## Client SDK
+The Vellum Client SDK, found within `src/client` is a low-level client used to interact directly with the Vellum API.
+Learn more and get started by visiting the [Vellum Client SDK README](/src/client/README.md).
+
+
+## Workflows SDK
+The Vellum Workflows SDK is a high-level framework for defining and debugging the control flow of AI systems. At
+it's core, it's a powerful workflow engine with syntactic sugar for intuitively defining graphs, the nodes within,
+and the relationships between them.
+
+The Workflows SDK can be used with or without a Vellum account, but a Vellum account is required to use certain
+out-of-box nodes and features, including the ability to push and pull your Workflow definition to Vellum for editing
+and debugging via a UI.
+
+To learn more and get started, visit the [Vellum Workflows SDK README](/src/workflows/README.md).
+
+
+## Open-Source vs. Paid
+
+This repo is available under the [MIT expat license](https://github.com/vellum-ai/vellum-python-sdks/blob/main/LICENSE), except
+for the `ee` directory (which has its [license here](https://github.com/vellum-ai/vellum-python-sdks/blob/main/ee/LICENSE)) if applicable.
+
+To learn more, [book a demo](https://www.vellum.ai/landing-pages/request-demo) or see our [pricing page](https://www.vellum.ai/pricing).

vellum_ai-0.10.0/ee/vellum_cli/__init__.py

@@ -0,0 +1,72 @@
+from typing import List, Optional
+
+import click
+
+from vellum_cli.aliased_group import ClickAliasedGroup
+from vellum_cli.image_push import image_push_command
+from vellum_cli.pull import pull_command
+from vellum_cli.push import push_command
+
+
+@click.group(cls=ClickAliasedGroup)
+def main() -> None:
+    """Vellum SDK CLI"""
+    pass
+
+
+@main.command()
+@click.argument("module", required=False)
+@click.option("--deploy", is_flag=True, help="Deploy the workflow after pushing it to Vellum")
+@click.option("--deployment-label", type=str, help="Label to use for the deployment")
+@click.option("--deployment-name", type=str, help="Unique name for the deployment")
+@click.option("--deployment-description", type=str, help="Description for the deployment")
+@click.option("--release-tag", type=list, help="Release tag for the deployment", multiple=True)
+def push(
+    module: Optional[str],
+    deploy: Optional[bool],
+    deployment_label: Optional[str],
+    deployment_name: Optional[str],
+    deployment_description: Optional[str],
+    release_tag: Optional[List[str]],
+) -> None:
+    """Push Workflow to Vellum"""
+    push_command(
+        module=module,
+        deploy=deploy,
+        deployment_label=deployment_label,
+        deployment_name=deployment_name,
+        deployment_description=deployment_description,
+        release_tags=release_tag,
+    )
+
+
+@main.command()
+@click.argument("module", required=False)
+@click.option("--legacy-module", is_flag=True, help="Pull the workflow as a legacy module")
+def pull(module: Optional[str], legacy_module: Optional[bool]) -> None:
+    """Pull Workflow from Vellum"""
+    pull_command(module, legacy_module)
+
+
+@main.group(aliases=["images", "image"])
+def images() -> None:
+    """Vellum Docker Images"""
+    pass
+
+
+@images.command(name="push")
+@click.argument("image", required=True)
+@click.option(
+    "--tag",
+    "-t",
+    multiple=True,
+    help="Tags the provided image inside of Vellum's repo. "
+    "This field does not push multiple local tags of the passed in image.",
+)
+def image_push(image: str, tag: Optional[List[str]] = None) -> None:
+    """Push Docker image to Vellum"""
+    image_push_command(image, tag)
+
+
+if __name__ == "__main__":
+    main()

vellum_ai-0.10.0/ee/vellum_cli/aliased_group.py

@@ -0,0 +1,103 @@
+"""
+    Extension for the python ``click`` module
+    to provide a group or command with aliases.
+    From https://github.com/click-contrib/click-aliases
+"""
+
+import typing as t
+
+import click
+
+_click7 = click.__version__[0] >= "7"
+
+
+class ClickAliasedGroup(click.Group):
+    def __init__(self, *args: t.Any, **kwargs: t.Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._commands: t.Dict[str, list[str]] = {}
+        self._aliases: t.Dict[str, str] = {}
+
+    def add_command(self, *args: t.Any, **kwargs: t.Any) -> None:
+        aliases = kwargs.pop("aliases", [])
+        super().add_command(*args, **kwargs)
+        if aliases:
+            cmd = args[0]
+            name = args[1] if len(args) > 1 else None
+            name = name or cmd.name
+            if name is None:
+                raise TypeError("Command has no name.")
+
+            self._commands[name] = aliases
+            for alias in aliases:
+                self._aliases[alias] = name
+
+    def command(self, *args: t.Any, **kwargs: t.Any) -> t.Any:
+        aliases = kwargs.pop("aliases", [])
+        decorator = super().command(*args, **kwargs)
+        if not aliases:
+            return decorator
+
+        def _decorator(f: t.Any) -> t.Any:
+            cmd = decorator(f)
+            if aliases:
+                self._commands[cmd.name] = aliases
+                for alias in aliases:
+                    self._aliases[alias] = cmd.name
+            return cmd
+
+        return _decorator
+
+    def group(self, *args: t.Any, **kwargs: t.Any) -> t.Any:
+        aliases = kwargs.pop("aliases", [])
+        decorator = super().group(*args, **kwargs)
+        if not aliases:
+            return decorator
+
+        def _decorator(f: t.Any) -> t.Any:
+            cmd = decorator(f)
+            if aliases:
+                self._commands[cmd.name] = aliases
+                for alias in aliases:
+                    self._aliases[alias] = cmd.name
+            return cmd
+
+        return _decorator
+
+    def resolve_alias(self, cmd_name: str) -> str:
+        if cmd_name in self._aliases:
+            return self._aliases[cmd_name]
+        return cmd_name
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> t.Optional[click.Command]:
+        cmd_name = self.resolve_alias(cmd_name)
+        command = super().get_command(ctx, cmd_name)
+        if command:
+            return command
+        return None
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        rows = []
+
+        sub_commands = self.list_commands(ctx)
+
+        max_len = 0
+        if len(sub_commands) > 0:
+            max_len = max(len(cmd) for cmd in sub_commands)
+
+        limit = formatter.width - 6 - max_len
+
+        for sub_command in sub_commands:
+            cmd = self.get_command(ctx, sub_command)
+            if cmd is None:
+                continue
+            if hasattr(cmd, "hidden") and cmd.hidden:
+                continue
+            if sub_command in self._commands:
+                aliases = ",".join(sorted(self._commands[sub_command]))
+                sub_command = f"{sub_command} ({aliases})"
+            cmd_help = cmd.get_short_help_str(limit) if _click7 else cmd.short_help or ""
+            rows.append((sub_command, cmd_help))
+
+        if rows:
+            with formatter.section("Commands"):
+                formatter.write_dl(rows)

vellum_ai-0.10.0/ee/vellum_cli/config.py

@@ -0,0 +1,96 @@
+from dataclasses import field
+import json
+import os
+from uuid import UUID
+from typing import Dict, List, Literal, Optional, Union
+
+import tomli
+
+from vellum.core.pydantic_utilities import UniversalBaseModel
+
+from vellum.workflows.state.encoder import DefaultStateEncoder
+
+LOCKFILE_PATH = "vellum.lock.json"
+PYPROJECT_TOML_PATH = "pyproject.toml"
+
+
+class WorkflowDeploymentConfig(UniversalBaseModel):
+    id: Optional[UUID] = None
+    label: Optional[str] = None
+    name: Optional[str] = None
+    description: Optional[str] = None
+    release_tags: Optional[List[str]] = None
+
+
+class WorkflowConfig(UniversalBaseModel):
+    module: str
+    workflow_sandbox_id: Optional[str] = None
+    ignore: Optional[Union[str, List[str]]] = None
+    deployments: List[WorkflowDeploymentConfig] = field(default_factory=list)
+
+    def merge(self, other: "WorkflowConfig") -> "WorkflowConfig":
+        return WorkflowConfig(
+            module=self.module,
+            workflow_sandbox_id=self.workflow_sandbox_id or other.workflow_sandbox_id,
+            ignore=self.ignore or other.ignore,
+        )
+
+
+class VellumCliConfig(UniversalBaseModel):
+    version: Literal["1.0"] = "1.0"
+    workflows: List[WorkflowConfig] = field(default_factory=list)
+
+    def save(self) -> None:
+        lockfile_path = os.path.join(os.getcwd(), LOCKFILE_PATH)
+        with open(lockfile_path, "w") as f:
+            json.dump(self.model_dump(), f, indent=2, cls=DefaultStateEncoder)
+
+    def merge(self, other: "VellumCliConfig") -> "VellumCliConfig":
+        if other.version != self.version:
+            raise ValueError("Lockfile version mismatch")
+
+        self_workflow_by_module = {workflow.module: workflow for workflow in self.workflows}
+        other_workflow_by_module = {workflow.module: workflow for workflow in other.workflows}
+        all_modules = sorted(set(self_workflow_by_module.keys()).union(set(other_workflow_by_module.keys())))
+        merged_workflows = []
+        for module in all_modules:
+            self_workflow = self_workflow_by_module.get(module)
+            other_workflow = other_workflow_by_module.get(module)
+            if self_workflow and other_workflow:
+                merged_workflows.append(self_workflow.merge(other_workflow))
+            elif self_workflow:
+                merged_workflows.append(self_workflow)
+            elif other_workflow:
+                merged_workflows.append(other_workflow)
+
+        return VellumCliConfig(workflows=merged_workflows, version=self.version)
+
+
+def load_vellum_cli_config(root_dir: Optional[str] = None) -> VellumCliConfig:
+    if root_dir is None:
+        root_dir = os.getcwd()
+    lockfile_path = os.path.join(root_dir, LOCKFILE_PATH)
+    if not os.path.exists(lockfile_path):
+        lockfile_data = {}
+    else:
+        with open(lockfile_path, "rb") as f:
+            lockfile_data = json.load(f)
+    lockfile_config = VellumCliConfig.model_validate(lockfile_data)
+
+    pyproject_toml_path = os.path.join(root_dir, PYPROJECT_TOML_PATH)
+    if not os.path.exists(pyproject_toml_path):
+        toml_vellum: Dict = {}
+    else:
+        with open(pyproject_toml_path, "rb") as f:
+            toml_loaded = tomli.load(f)
+        toml_tool = toml_loaded.get("tool", {})
+        if not isinstance(toml_tool, dict):
+            toml_vellum = {}
+
+        toml_vellum = toml_tool.get("vellum")
+        if not isinstance(toml_vellum, dict):
+            # Mypy is wrong. this is totally reachable.
+            toml_vellum = {}  # type: ignore[unreachable]
+    toml_config = VellumCliConfig.model_validate(toml_vellum)
+
+    return toml_config.merge(lockfile_config)

vellum_ai-0.10.0/ee/vellum_cli/image_push.py

@@ -0,0 +1,112 @@
+import json
+import logging
+import subprocess
+from typing import List, Optional
+
+import docker
+from docker import DockerClient
+from dotenv import load_dotenv
+
+from vellum_cli.logger import load_cli_logger
+from vellum.workflows.vellum_client import create_vellum_client
+
+_SUPPORTED_ARCHITECTURE = "amd64"
+
+
+def image_push_command(image: str, tags: Optional[List[str]] = None) -> None:
+    load_dotenv()
+    logger = load_cli_logger()
+    vellum_client = create_vellum_client()
+
+    # We're using docker python SDK here instead of subprocess since it connects to the docker host directly
+    # instead of using the command line so it seemed like it would possibly be a little more robust since
+    # it might avoid peoples' wonky paths, unfortunately it doesn't support the manifest command which we need for
+    # listing all of the architectures of the image instead of just the one that matches the machine. We can fall back
+    # to using normal inspect which returns the machine image for this case though. And in the future we could figure
+    # out how to call the docker host directly to do this.
+    docker_client = docker.from_env()
+    check_architecture(docker_client, image, logger)
+
+    auth = vellum_client.container_images.docker_service_token()
+
+    docker_client.login(
+        username="oauth2accesstoken",
+        password=auth.access_token,
+        registry=auth.repository,
+    )
+
+    repo_split = image.split("/")
+    tag_split = repo_split[-1].split(":")
+    image_name = tag_split[0]
+    main_tag = tag_split[1] if len(tag_split) > 1 else "latest"
+
+    all_tags = [main_tag, *(tags or [])]
+    for tag in all_tags:
+        vellum_image_name = f"{auth.repository}/{image_name}:{tag}"
+
+        docker_client.api.tag(image, vellum_image_name)
+
+        push_result = docker_client.images.push(repository=vellum_image_name, stream=True)
+
+        # Here were trying to mime the output you would get from a normal docker push, which
+        # the python sdk makes as hard as possible.
+        for raw_line in push_result:
+            try:
+                for sub_line in raw_line.decode("utf-8").split("\r\n"):
+                    line = json.loads(sub_line)
+                    error_message = line.get("errorDetail", {}).get("message")
+                    status = line.get("status")
+                    id = line.get("id", "")
+
+                    if error_message:
+                        logger.error(error_message)
+                        exit(1)
+                    elif status == "Waiting":
+                        continue
+                    elif status:
+                        logger.info(f"{id}{': ' if id else ''}{status}")
+                    else:
+                        logger.info(line)
+            except Exception:
+                continue
+
+    logger.info("Updating Vellum metadata and enforcing the first law of robotics...")
+    image_details = docker_client.api.inspect_image(image)
+    sha = image_details["Id"]
+
+    vellum_client.container_images.push_container_image(
+        name=image_name,
+        sha=sha,
+        tags=all_tags,
+    )
+    logger.info(f"Image successfully pushed as {image_name} to vellum with tags: {all_tags}.")
+
+
+def check_architecture(docker_client: DockerClient, image: str, logger: logging.Logger) -> None:
+    result = subprocess.run(
+        ["docker", "manifest", "inspect", image],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+
+    manifest_parse_failed = False
+    architectures = []
+    try:
+        manifest = json.loads(result.stdout)
+        architectures = [manifest_item["platform"]["architecture"] for manifest_item in manifest["manifests"]]
+    except Exception:
+        logger.warning("Error parsing manifest response")
+        manifest_parse_failed = True
+
+    # Fall back to inspect image if we errored out using docker command line
+    if result.returncode != 0 or manifest_parse_failed:
+        logger.warning(f"Error inspecting manifest: {result.stderr.decode('utf-8').strip()}")
+        image_details = docker_client.api.inspect_image(image)
+
+        if image_details["Architecture"] != _SUPPORTED_ARCHITECTURE:
+            logger.error(f"Image must be built for {_SUPPORTED_ARCHITECTURE} architecture.")
+            exit(1)
+    else:
+        if _SUPPORTED_ARCHITECTURE not in architectures:
+            logger.error(f"Image must be built for {_SUPPORTED_ARCHITECTURE} architecture.")
+            exit(1)

vellum_ai-0.10.0/ee/vellum_cli/logger.py

@@ -0,0 +1,36 @@
+import logging
+import os
+
+
+class CLIFormatter(logging.Formatter):
+    grey = "\x1b[38;20m"
+    yellow = "\x1b[33;20m"
+    red = "\x1b[31;20m"
+    bold_red = "\x1b[31;1m"
+    white = "\33[37m"
+    reset = "\x1b[0m"
+    message_format = "%(message)s"
+
+    FORMATS = {
+        logging.DEBUG: white + message_format + reset,
+        logging.INFO: grey + message_format + reset,
+        logging.WARNING: yellow + message_format + reset,
+        logging.ERROR: red + message_format + reset,
+        logging.CRITICAL: bold_red + message_format + reset,
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_fmt = self.FORMATS.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+def load_cli_logger() -> logging.Logger:
+    logger = logging.getLogger(__package__)
+    logger.setLevel(os.getenv("LOG_LEVEL", logging.INFO))
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(CLIFormatter())
+    logger.addHandler(handler)
+
+    return logger

vellum_ai-0.10.0/ee/vellum_cli/pull.py

@@ -0,0 +1,73 @@
+import io
+import os
+from pathlib import Path
+import zipfile
+from typing import Optional
+
+from dotenv import load_dotenv
+
+from vellum_cli.config import load_vellum_cli_config
+from vellum_cli.logger import load_cli_logger
+from vellum.workflows.vellum_client import create_vellum_client
+
+
+def pull_command(module: Optional[str], legacy_module: Optional[bool] = None) -> None:
+    load_dotenv()
+    logger = load_cli_logger()
+    config = load_vellum_cli_config()
+
+    if not config.workflows:
+        raise ValueError("No Workflows found in project to pull.")
+
+    if len(config.workflows) > 1 and not module:
+        raise ValueError("Multiple workflows found in project to pull. Pulling only a single workflow is supported.")
+
+    workflow_config = next((w for w in config.workflows if w.module == module), None) if module else config.workflows[0]
+    if workflow_config is None:
+        raise ValueError(f"No workflow config for '{module}' found in project to push.")
+
+    if not workflow_config.workflow_sandbox_id:
+        raise ValueError("No workflow sandbox ID found in project to pull from.")
+
+    logger.info(f"Pulling workflow into {workflow_config.module}")
+    client = create_vellum_client()
+    response = client.workflows.pull(
+        workflow_config.workflow_sandbox_id,
+        request_options={"additional_query_parameters": {"legacyModule": legacy_module} if legacy_module else {}},
+    )
+
+    zip_bytes = b"".join(response)
+    zip_buffer = io.BytesIO(zip_bytes)
+
+    target_dir = os.path.join(os.getcwd(), *workflow_config.module.split("."))
+    with zipfile.ZipFile(zip_buffer) as zip_file:
+        # Delete files in target_dir that aren't in the zip file
+        if os.path.exists(target_dir):
+            ignore_patterns = (
+                workflow_config.ignore
+                if isinstance(workflow_config.ignore, list)
+                else [workflow_config.ignore] if isinstance(workflow_config.ignore, str) else []
+            )
+            existing_files = []
+            for root, _, files in os.walk(target_dir):
+                for file in files:
+                    rel_path = os.path.relpath(os.path.join(root, file), target_dir)
+                    existing_files.append(rel_path)
+
+            for file in existing_files:
+                if any(Path(file).match(ignore_pattern) for ignore_pattern in ignore_patterns):
+                    continue
+
+                if file not in zip_file.namelist():
+                    file_path = os.path.join(target_dir, file)
+                    logger.info(f"Deleting {file_path}...")
+                    os.remove(file_path)
+
+        for file_name in zip_file.namelist():
+            target_file = os.path.join(target_dir, file_name)
+            os.makedirs(os.path.dirname(target_file), exist_ok=True)
+            with zip_file.open(file_name) as source, open(target_file, "w") as target:
+                logger.info(f"Writing to {target_file}...")
+                target.write(source.read().decode("utf-8"))
+
+    logger.info(f"Successfully pulled Workflow into {workflow_config.module}")