vellum-ai 0.10.9__tar.gz → 0.11.1__tar.gz

vellum_ai-0.11.1/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.1
+Name: vellum-ai
+Version: 0.11.1
+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/vellum/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/vellum/workflows/README.md).
+
+## Contributing
+
+See the [CONTRIBUTING.md](/CONTRIBUTING.md) for information on how to contribute to the Vellum SDKs.
+
+## 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.11.1/ee/vellum_cli/__init__.py

@@ -0,0 +1,226 @@
+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
+
+
+class PushGroup(ClickAliasedGroup):
+    def get_command(self, ctx, cmd_name):
+        # First try to get the command normally
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd
+
+        # If no command found, call our catch-all
+        return push_module
+
+
+@main.group(invoke_without_command=True, cls=PushGroup)
+@click.pass_context
+def push(
+    ctx: click.Context,
+) -> None:
+    """Push Resources to Vellum"""
+
+    if ctx.invoked_subcommand is None:
+        push_command()
+
+
+@main.group()
+def workflows():
+    """Operations related to Vellum Workflows"""
+    pass
+
+
+@workflows.command(name="push")
+@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 workflows_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 Workflows to Vellum. If a module is provided, only the Workflow for that module will be pushed.
+    If no module is provided, the first configured Workflow will be pushed.
+    """
+
+    push_command(
+        module=module,
+        deploy=deploy,
+        deployment_label=deployment_label,
+        deployment_name=deployment_name,
+        deployment_description=deployment_description,
+        release_tags=release_tag,
+    )
+
+
+@push.command(name="*", hidden=True)
+@click.pass_context
+@click.option("--deploy", is_flag=True, help="Deploy the Resource 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(
+    ctx: click.Context,
+    deploy: Optional[bool],
+    deployment_label: Optional[str],
+    deployment_name: Optional[str],
+    deployment_description: Optional[str],
+    release_tag: Optional[List[str]],
+) -> None:
+    """Push a specific module to Vellum"""
+
+    if ctx.parent:
+        push_command(
+            module=ctx.parent.invoked_subcommand,
+            deploy=deploy,
+            deployment_label=deployment_label,
+            deployment_name=deployment_name,
+            deployment_description=deployment_description,
+            release_tags=release_tag,
+        )
+
+
+class PullGroup(ClickAliasedGroup):
+    def get_command(self, ctx, cmd_name):
+        # First try to get the command normally
+        cmd = super().get_command(ctx, cmd_name)
+        if cmd is not None:
+            return cmd
+
+        # If no command found, call our catch-all
+        return pull_module
+
+
+@main.group(invoke_without_command=True, cls=PullGroup)
+@click.pass_context
+@click.option(
+    "--include-json",
+    is_flag=True,
+    help="""Include the JSON representation of each Resource in the pull response. \
+Should only be used for debugging purposes.""",
+)
+@click.option(
+    "--exclude-code",
+    is_flag=True,
+    help="""Exclude the code definition of each Resource from the pull response. \
+Should only be used for debugging purposes.""",
+)
+def pull(
+    ctx: click.Context,
+    include_json: Optional[bool],
+    exclude_code: Optional[bool],
+) -> None:
+    """Pull Resources from Vellum"""
+
+    if ctx.invoked_subcommand is None:
+        pull_command(
+            include_json=include_json,
+            exclude_code=exclude_code,
+        )
+
+
+@workflows.command(name="pull")
+@click.argument("module", required=False)
+@click.option(
+    "--include-json",
+    is_flag=True,
+    help="""Include the JSON representation of the Workflow in the pull response. \
+Should only be used for debugging purposes.""",
+)
+@click.option("--workflow-sandbox-id", type=str, help="Pull the Workflow from a specific Sandbox ID")
+@click.option(
+    "--exclude-code",
+    is_flag=True,
+    help="""Exclude the code definition of the Workflow from the pull response. \
+Should only be used for debugging purposes.""",
+)
+def workflows_pull(
+    module: Optional[str],
+    include_json: Optional[bool],
+    workflow_sandbox_id: Optional[str],
+    exclude_code: Optional[bool],
+) -> None:
+    """
+    Pull Workflows from Vellum. If a module is provided, only the Workflow for that module will be pulled.
+    If no module is provided, the first configured Workflow will be pulled.
+    """
+
+    pull_command(
+        module=module,
+        include_json=include_json,
+        workflow_sandbox_id=workflow_sandbox_id,
+        exclude_code=exclude_code,
+    )
+
+
+@pull.command(name="*")
+@click.pass_context
+@click.option(
+    "--include-json",
+    is_flag=True,
+    help="""Include the JSON representation of the Resource in the pull response. \
+Should only be used for debugging purposes.""",
+)
+@click.option(
+    "--exclude-code",
+    is_flag=True,
+    help="""Exclude the code definition of the Resource from the pull response. \
+Should only be used for debugging purposes.""",
+)
+def pull_module(
+    ctx: click.Context,
+    include_json: Optional[bool],
+    exclude_code: Optional[bool],
+) -> None:
+    """Pull a specific module from Vellum"""
+
+    if ctx.parent:
+        pull_command(
+            module=ctx.parent.invoked_subcommand,
+            include_json=include_json,
+            exclude_code=exclude_code,
+        )
+
+
+@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.11.1/ee/vellum_cli/config.py

@@ -0,0 +1,95 @@
+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.11.1/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.workflows.vellum_client import create_vellum_client
+from vellum_cli.logger import load_cli_logger
+
+_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.11.1/ee/vellum_cli/pull.py

@@ -0,0 +1,113 @@
+import io
+import os
+from pathlib import Path
+import zipfile
+from typing import Optional
+
+from dotenv import load_dotenv
+
+from vellum.workflows.vellum_client import create_vellum_client
+from vellum_cli.config import VellumCliConfig, WorkflowConfig, load_vellum_cli_config
+from vellum_cli.logger import load_cli_logger
+
+
+def resolve_workflow_config(
+    config: VellumCliConfig,
+    module: Optional[str] = None,
+    workflow_sandbox_id: Optional[str] = None,
+) -> Optional[WorkflowConfig]:
+    if module:
+        return next((w for w in config.workflows if w.module == module), None)
+    elif workflow_sandbox_id:
+        workflow_config = WorkflowConfig(
+            workflow_sandbox_id=workflow_sandbox_id,
+            module=f"workflow_{workflow_sandbox_id.split('-')[0]}",
+        )
+        config.workflows.append(workflow_config)
+        return workflow_config
+    elif config.workflows:
+        return config.workflows[0]
+
+    return None
+
+
+def pull_command(
+    module: Optional[str] = None,
+    workflow_sandbox_id: Optional[str] = None,
+    include_json: Optional[bool] = None,
+    exclude_code: Optional[bool] = None,
+) -> None:
+    load_dotenv()
+    logger = load_cli_logger()
+    config = load_vellum_cli_config()
+
+    workflow_config = resolve_workflow_config(
+        config,
+        module,
+        workflow_sandbox_id,
+    )
+    save_lock_file = not module
+
+    if not workflow_config:
+        raise ValueError("No workflow config found in project to pull from.")
+
+    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()
+    query_parameters = {}
+    if include_json:
+        query_parameters["include_json"] = include_json
+    if exclude_code:
+        query_parameters["exclude_code"] = exclude_code
+
+    response = client.workflows.pull(
+        workflow_config.workflow_sandbox_id,
+        request_options={"additional_query_parameters": query_parameters},
+    )
+
+    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"))
+
+    if include_json:
+        logger.warning(
+            """The pulled JSON representation of the Workflow should be used for debugging purposely only. \
+Its schema should be considered unstable and subject to change at any time."""
+        )
+
+    if save_lock_file:
+        config.save()
+
+    logger.info(f"Successfully pulled Workflow into {workflow_config.module}")