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

vellum_ai-1.13.5.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+generate_node_definitions=vellum_ee.scripts.generate_node_definitions:main
+vellum=vellum_cli:main
+

vellum_cli/__init__.py

@@ -5,6 +5,7 @@ import click
 from vellum_cli.aliased_group import ClickAliasedGroup
 from vellum_cli.image_push import image_push_command
 from vellum_cli.init import init_command
+from vellum_cli.move import move_command
 from vellum_cli.ping import ping_command
 from vellum_cli.pull import pull_command
 from vellum_cli.push import push_command
@@ -67,7 +68,8 @@ with the provided module or be available for use. The Workflow Sandbox must also
 @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)
+@click.option("--release-tag", help="Release Tag for the Deployment", multiple=True)
+@click.option("--release-description", type=str, help="Description for the Release")
 @click.option(
     "--dry-run",
     is_flag=True,
@@ -87,6 +89,7 @@ def workflows_push(
     deployment_name: Optional[str],
     deployment_description: Optional[str],
     release_tag: Optional[List[str]],
+    release_description: Optional[str],
     dry_run: Optional[bool],
     strict: Optional[bool],
     workspace: Optional[str],
@@ -104,6 +107,7 @@ def workflows_push(
         deployment_name=deployment_name,
         deployment_description=deployment_description,
         release_tags=release_tag,
+        release_description=release_description,
         dry_run=dry_run,
         strict=strict,
         workspace=workspace,
@@ -117,7 +121,8 @@ def workflows_push(
 @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)
+@click.option("--release-tag", help="Release Tag for the Deployment", multiple=True)
+@click.option("--release-description", type=str, help="Description for the Release")
 @click.option(
     "--dry-run",
     is_flag=True,
@@ -137,6 +142,7 @@ def push_module(
     deployment_name: Optional[str],
     deployment_description: Optional[str],
     release_tag: Optional[List[str]],
+    release_description: Optional[str],
     dry_run: Optional[bool],
     strict: Optional[bool],
     workspace: Optional[str],
@@ -152,6 +158,7 @@ def push_module(
             deployment_name=deployment_name,
             deployment_description=deployment_description,
             release_tags=release_tag,
+            release_description=release_description,
             dry_run=dry_run,
             strict=strict,
             workspace=workspace,
@@ -201,6 +208,11 @@ Helpful for running and debugging workflows locally.""",
     help="""Directory to pull the workflow into. If not specified, \
 the workflow will be pulled into the current working directory.""",
 )
+@click.option(
+    "--release-tag",
+    type=str,
+    help="""Release tag to use when pulling from a deployment.""",
+)
 def pull(
     ctx: click.Context,
     include_json: Optional[bool],
@@ -208,6 +220,7 @@ def pull(
     strict: Optional[bool],
     include_sandbox: Optional[bool],
     target_directory: Optional[str],
+    release_tag: Optional[str],
 ) -> None:
     """Pull Resources from Vellum"""
 
@@ -218,6 +231,7 @@ def pull(
             strict=strict,
             include_sandbox=include_sandbox,
             target_directory=target_directory,
+            release_tag=release_tag,
         )
 
 
@@ -264,6 +278,11 @@ the workflow will be pulled into the current working directory.""",
     type=str,
     help="The specific Workspace config to use when pulling",
 )
+@click.option(
+    "--release-tag",
+    type=str,
+    help="""Release tag to use when pulling from a deployment.""",
+)
 def workflows_pull(
     module: Optional[str],
     include_json: Optional[bool],
@@ -274,6 +293,7 @@ def workflows_pull(
     include_sandbox: Optional[bool],
     target_directory: Optional[str],
     workspace: Optional[str],
+    release_tag: Optional[str],
 ) -> None:
     """
     Pull Workflows from Vellum. If a module is provided, only the Workflow for that module will be pulled.
@@ -290,6 +310,7 @@ def workflows_pull(
         include_sandbox=include_sandbox,
         target_directory=target_directory,
         workspace=workspace,
+        release_tag=release_tag,
     )
 
 
@@ -325,6 +346,11 @@ Helpful for running and debugging resources locally.""",
     help="""Directory to pull the workflow into. If not specified, \
 the workflow will be pulled into the current working directory.""",
 )
+@click.option(
+    "--release-tag",
+    type=str,
+    help="""Release tag to use when pulling from a deployment.""",
+)
 def pull_module(
     ctx: click.Context,
     include_json: Optional[bool],
@@ -332,6 +358,7 @@ def pull_module(
     strict: Optional[bool],
     include_sandbox: Optional[bool],
     target_directory: Optional[str],
+    release_tag: Optional[str],
 ) -> None:
     """Pull a specific module from Vellum"""
 
@@ -343,6 +370,7 @@ def pull_module(
             strict=strict,
             include_sandbox=include_sandbox,
             target_directory=target_directory,
+            release_tag=release_tag,
         )
 
 
@@ -362,9 +390,32 @@ def images() -> None:
     "This field does not push multiple local tags of the passed in image.",
 )
 @click.option("--workspace", type=str, help="The specific Workspace config to use when pushing")
-def image_push(image: str, tag: Optional[List[str]] = None, workspace: Optional[str] = None) -> None:
+@click.option("--source", type=str, help="Path to Dockerfile to build before pushing")
+def image_push(
+    image: str, tag: Optional[List[str]] = None, workspace: Optional[str] = None, source: Optional[str] = None
+) -> None:
     """Push Docker image to Vellum"""
-    image_push_command(image, tag, workspace)
+    image_push_command(image, tag, workspace, source)
+
+
+@workflows.command(name="move")
+@click.argument("old_module", required=True)
+@click.argument("new_module", required=True)
+@click.option("--workspace", type=str, help="The specific Workspace config to use when moving")
+def workflows_move(
+    old_module: str,
+    new_module: str,
+    workspace: Optional[str],
+) -> None:
+    """
+    Move/rename a Workflow module. Updates both the filesystem structure and configuration.
+    """
+
+    move_command(
+        old_module=old_module,
+        new_module=new_module,
+        workspace=workspace,
+    )
 
 
 @workflows.command(name="init")

vellum_cli/config.py

@@ -7,8 +7,8 @@ from typing import Dict, List, Literal, Optional, Union
 
 import tomli
 
-from vellum.core.pydantic_utilities import UniversalBaseModel
-from vellum.workflows.state.encoder import DefaultStateEncoder
+from vellum.client.core.pydantic_utilities import UniversalBaseModel
+from vellum.utils.json_encoder import VellumJsonEncoder
 
 LOCKFILE_PATH = "vellum.lock.json"
 PYPROJECT_TOML_PATH = "pyproject.toml"
@@ -36,6 +36,7 @@ class WorkflowDeploymentConfig(UniversalBaseModel):
     name: Optional[str] = None
     description: Optional[str] = None
     release_tags: Optional[List[str]] = None
+    release_description: Optional[str] = None
 
     def merge(self, other: "WorkflowDeploymentConfig") -> "WorkflowDeploymentConfig":
         return WorkflowDeploymentConfig(
@@ -44,6 +45,7 @@ class WorkflowDeploymentConfig(UniversalBaseModel):
             name=self.name or other.name,
             description=self.description or other.description,
             release_tags=self.release_tags or other.release_tags,
+            release_description=self.release_description or other.release_description,
         )
 
 
@@ -118,22 +120,36 @@ def merge_workflows_by_sandbox_id(
         else:
             # If the user defines a workflow in the pyproject.toml with a sandbox_id,
             # we merge the workflow with one of the ones in the lockfile with the same sandbox_id.
+            # First, try to find a lockfile workflow matching both sandbox_id AND workspace.
             other_workflow = next(
                 (
                     other_workflow
                     for other_workflow in other_workflows
                     if self_workflow.workflow_sandbox_id == other_workflow.workflow_sandbox_id
+                    and self_workflow.workspace == other_workflow.workspace
                 ),
                 None,
             )
+            # If no exact match, fall back to matching by sandbox_id alone.
+            if other_workflow is None:
+                other_workflow = next(
+                    (
+                        other_workflow
+                        for other_workflow in other_workflows
+                        if self_workflow.workflow_sandbox_id == other_workflow.workflow_sandbox_id
+                    ),
+                    None,
+                )
             if other_workflow is not None:
                 merged_workflows.append(self_workflow.merge(other_workflow))
             else:
                 merged_workflows.append(self_workflow)
 
-    workflow_sandbox_ids_so_far = {workflow.workflow_sandbox_id for workflow in merged_workflows}
+    # Use (workflow_sandbox_id, workspace) as the dedupe key to preserve workflows
+    # with the same sandbox_id but different workspaces.
+    workflow_keys_so_far = {(workflow.workflow_sandbox_id, workflow.workspace) for workflow in merged_workflows}
     for other_workflow in other_workflows:
-        if other_workflow.workflow_sandbox_id not in workflow_sandbox_ids_so_far:
+        if (other_workflow.workflow_sandbox_id, other_workflow.workspace) not in workflow_keys_so_far:
             merged_workflows.append(other_workflow)
 
     return merged_workflows
@@ -147,7 +163,7 @@ class VellumCliConfig(UniversalBaseModel):
     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)
+            json.dump(self.model_dump(), f, indent=2, cls=VellumJsonEncoder)
             # Makes sure the file ends with a newline, consistent with most autoformatters
             f.write("\n")
 

vellum_cli/image_push.py

@@ -9,17 +9,47 @@ import docker
 from docker import DockerClient
 from dotenv import load_dotenv
 
+from vellum.client.core.api_error import ApiError
 from vellum.workflows.vellum_client import create_vellum_client, create_vellum_environment
 from vellum_cli.config import DEFAULT_WORKSPACE_CONFIG, load_vellum_cli_config
-from vellum_cli.logger import load_cli_logger
+from vellum_cli.logger import handle_cli_error, load_cli_logger
 
 _SUPPORTED_ARCHITECTURE = "amd64"
 
 
-def image_push_command(image: str, tags: Optional[List[str]] = None, workspace: Optional[str] = None) -> None:
+def image_push_command(
+    image: str, tags: Optional[List[str]] = None, workspace: Optional[str] = None, source: Optional[str] = None
+) -> None:
     load_dotenv(dotenv_path=os.path.join(os.getcwd(), ".env"))
     logger = load_cli_logger()
     config = load_vellum_cli_config()
+
+    logger.info("Cleaning up unused Docker images...")
+    try:
+        subprocess.run(
+            ["docker", "image", "prune", "--all", "-f", "--filter", "label=image-type=python-workflow-runtime"],
+            check=True,
+        )
+        logger.info("Docker image pruning completed successfully")
+    except subprocess.CalledProcessError as e:
+        logger.warning(f"Docker image pruning failed: {e}")
+
+    if source:
+        logger.info(f"Building Docker image from Dockerfile: {source}")
+
+        if not os.path.exists(source):
+            handle_cli_error(logger, "Dockerfile not found", f"Dockerfile does not exist: {source}")
+
+        build_result = subprocess.run(
+            ["docker", "buildx", "build", "-f", source, "--platform=linux/amd64", "-t", image, "."],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+
+        if build_result.returncode != 0:
+            handle_cli_error(logger, "Docker build failed", build_result.stderr.decode("utf-8"))
+
+        logger.info("Docker build completed successfully")
     workspace_config = next((w for w in config.workspaces if w.name == workspace), DEFAULT_WORKSPACE_CONFIG)
 
     api_key = os.getenv(workspace_config.api_key, None)
@@ -82,7 +112,41 @@ def image_push_command(image: str, tags: Optional[List[str]] = None, workspace:
             exit(1)
     else:
         logger.info("Authenticating...")
-        auth = vellum_client.container_images.docker_service_token()
+        try:
+            auth = vellum_client.container_images.docker_service_token()
+        except ApiError as e:
+            if e.status_code == 401 or e.status_code == 403:
+                handle_cli_error(
+                    logger,
+                    title="Authentication failed",
+                    message="Unable to authenticate with Vellum API. Please check your API key.",
+                    suggestion="Make sure your VELLUM_API_KEY environment variable is set correctly.",
+                )
+                return
+            elif e.status_code == 400 and isinstance(e.body, dict) and "detail" in e.body:
+                handle_cli_error(
+                    logger,
+                    title="API request failed",
+                    message=e.body["detail"],
+                )
+                return
+            elif e.status_code == 500:
+                handle_cli_error(
+                    logger,
+                    title="Server error",
+                    message="The Vellum API failed with an unexpected server error.",
+                    suggestion="Please try again later and contact support if the problem persists.",
+                )
+                return
+            else:
+                handle_cli_error(
+                    logger,
+                    title="API request failed",
+                    message=f"Failed to get Docker service token from Vellum API (HTTP {e.status_code}).",
+                    suggestion="Please check your configuration and try again. If the problem persists, "
+                    "contact support.",
+                )
+                return
 
         docker_client.login(
             username="oauth2accesstoken",
@@ -143,11 +207,45 @@ def image_push_command(image: str, tags: Optional[List[str]] = None, workspace:
 
     logger.info(f"Updating Vellum metadata and validating image works in our system with image digest: {sha}...")
 
-    vellum_client.container_images.push_container_image(
-        name=image_name,
-        sha=sha,
-        tags=all_tags,
-    )
+    try:
+        vellum_client.container_images.push_container_image(
+            name=image_name,
+            sha=sha,
+            tags=all_tags,
+        )
+    except ApiError as e:
+        if e.status_code == 401 or e.status_code == 403:
+            handle_cli_error(
+                logger,
+                title="Authentication failed",
+                message="Unable to push container image metadata to Vellum API. Please check your API key.",
+                suggestion="Make sure your VELLUM_API_KEY environment variable is set correctly.",
+            )
+            return
+        elif e.status_code == 400 and isinstance(e.body, dict) and "detail" in e.body:
+            handle_cli_error(
+                logger,
+                title="API request failed",
+                message=e.body["detail"],
+            )
+            return
+        elif e.status_code == 500:
+            handle_cli_error(
+                logger,
+                title="Server error",
+                message="The Vellum API failed with an unexpected server error while pushing container image metadata.",
+                suggestion="Please try again later and contact support if the problem persists.",
+            )
+            return
+        else:
+            handle_cli_error(
+                logger,
+                title="API request failed",
+                message=f"Failed to push container image metadata to Vellum API (HTTP {e.status_code}).",
+                suggestion="Please check your configuration and try again. If the problem persists, contact support.",
+            )
+            return
+
     logger.info(f"Image successfully pushed as {image_name} to vellum with tags: {all_tags}.")
 
 

vellum_cli/move.py

@@ -0,0 +1,56 @@
+import os
+import shutil
+from typing import Optional
+
+from dotenv import load_dotenv
+
+from vellum_cli.config import DEFAULT_WORKSPACE_CONFIG, load_vellum_cli_config
+from vellum_cli.logger import load_cli_logger
+from vellum_cli.push import module_exists
+
+
+def move_command(
+    old_module: str,
+    new_module: str,
+    workspace: Optional[str] = None,
+) -> None:
+    load_dotenv(dotenv_path=os.path.join(os.getcwd(), ".env"))
+    logger = load_cli_logger()
+    config = load_vellum_cli_config()
+
+    if not module_exists(old_module):
+        raise ValueError(f"Module '{old_module}' does not exist in the filesystem.")
+
+    if module_exists(new_module):
+        raise ValueError(f"Module '{new_module}' already exists. Cannot move to existing module.")
+
+    matching_configs = [w for w in config.workflows if w.module == old_module]
+
+    if workspace:
+        matching_configs = [w for w in matching_configs if w.workspace == workspace]
+    else:
+        matching_configs = [w for w in matching_configs if w.workspace == DEFAULT_WORKSPACE_CONFIG.name]
+
+    if not matching_configs:
+        workspace_msg = (
+            f" in workspace '{workspace}'" if workspace else f" in workspace '{DEFAULT_WORKSPACE_CONFIG.name}'"
+        )
+        raise ValueError(f"No workflow configuration found for module '{old_module}'{workspace_msg}.")
+
+    logger.info(f"Moving module from '{old_module}' to '{new_module}'...")
+
+    old_path = os.path.join(os.getcwd(), *old_module.split("."))
+    new_path = os.path.join(os.getcwd(), *new_module.split("."))
+
+    os.makedirs(os.path.dirname(new_path), exist_ok=True)
+
+    shutil.move(old_path, new_path)
+    logger.info(f"Moved filesystem directory from '{old_path}' to '{new_path}'")
+
+    for workflow_config in matching_configs:
+        workflow_config.module = new_module
+        logger.info(f"Updated workflow configuration: {workflow_config.workflow_sandbox_id}")
+
+    config.save()
+    logger.info("Updated vellum.lock.json file.")
+    logger.info(f"Successfully moved module from '{old_module}' to '{new_module}'")

vellum_cli/ping.py

@@ -14,6 +14,7 @@ def ping_command():
     try:
         workspace = client.workspaces.workspace_identity()
         organization = client.organizations.organization_identity()
+        environment = client.environments.environment_identity()
     except ApiError as e:
         # If user did not provide an API key, we will get a 403 error
         if e.status_code == 401 or e.status_code == 403:
@@ -35,5 +36,10 @@ Organization:
 Workspace:
     ID: {workspace.id}
     Name: {workspace.name}
+
+Environment:
+    ID: {environment.id}
+    Name: {environment.name}
+    Label: {environment.label}
 """
     )

vellum_cli/pull.py

@@ -7,11 +7,11 @@ import zipfile
 from typing import Optional
 
 from dotenv import load_dotenv
-from pydash import snake_case
 
 from vellum.client.core.api_error import ApiError
 from vellum.client.core.pydantic_utilities import UniversalBaseModel
 from vellum.utils.uuid import is_valid_uuid
+from vellum.workflows.utils.names import create_module_name
 from vellum.workflows.vellum_client import create_vellum_client
 from vellum_cli.config import (
     DEFAULT_WORKSPACE_CONFIG,
@@ -20,7 +20,7 @@ from vellum_cli.config import (
     WorkflowDeploymentConfig,
     load_vellum_cli_config,
 )
-from vellum_cli.logger import load_cli_logger
+from vellum_cli.logger import handle_cli_error, load_cli_logger
 
 ERROR_LOG_FILE_NAME = "error.log"
 METADATA_FILE_NAME = "metadata.json"
@@ -41,7 +41,11 @@ class PullContentsMetadata(UniversalBaseModel):
     runner_config: Optional[RunnerConfig] = None
     deployment_id: Optional[UUID] = None
     deployment_name: Optional[str] = None
+    deployment_history_item_id: Optional[UUID] = None
+    release_tag_id: Optional[UUID] = None
+    release_tag_name: Optional[str] = None
     workflow_sandbox_id: Optional[UUID] = None
+    workflow_version_id: Optional[UUID] = None
 
 
 def _resolve_workflow_config(
@@ -141,6 +145,7 @@ def pull_command(
     include_sandbox: Optional[bool] = None,
     target_directory: Optional[str] = None,
     workspace: Optional[str] = None,
+    release_tag: Optional[str] = None,
 ) -> None:
     load_dotenv(dotenv_path=os.path.join(os.getcwd(), ".env"))
     logger = load_cli_logger()
@@ -194,6 +199,7 @@ def pull_command(
 
     response = client.workflows.pull(
         pk,
+        release_tag=release_tag,
         request_options={"additional_query_parameters": query_parameters},
     )
 
@@ -201,16 +207,42 @@ def pull_command(
         zip_bytes = b"".join(response)
     except ApiError as e:
         if e.status_code == 401 or e.status_code == 403:
-            raise Exception("Please make sure your `VELLUM_API_KEY` environment variable is set correctly.")
+            handle_cli_error(
+                logger,
+                title="Authentication failed",
+                message="Unable to authenticate with the Vellum API.",
+                suggestion="Please make sure your `VELLUM_API_KEY` environment variable is set correctly and that you have access to this workflow.",  # noqa: E501
+            )
+
+        if e.status_code == 404:
+            handle_cli_error(
+                logger,
+                title="Workflow not found",
+                message=f"The workflow with ID '{pk}' could not be found.",
+                suggestion="Please verify the workflow ID is correct and that you have access to it in your workspace.",
+            )
 
         if e.status_code == 500:
-            raise Exception(
-                "The Pull API failed with an unexpected error. Please try again later and contact support if the problem persists."  # noqa: E501
+            handle_cli_error(
+                logger,
+                title="Server error occurred",
+                message="The Vellum API encountered an internal server error while processing your request.",
+                suggestion="Please try again in a few moments. If the problem persists, contact Vellum support with the workflow ID and timestamp.",  # noqa: E501
             )
 
-        # TODO: We should return an Origin header in to validate this case
-        raise Exception(
-            "The API we tried to pull is invalid. Please make sure your `VELLUM_API_URL` environment variable is set correctly."  # noqa: E501
+        if e.status_code == 502 or e.status_code == 503 or e.status_code == 504:
+            handle_cli_error(
+                logger,
+                title="Service temporarily unavailable",
+                message="The Vellum API is temporarily unavailable or experiencing high load.",
+                suggestion="Please wait a moment and try again. If the issue continues, check the Vellum status page or contact support.",  # noqa: E501
+            )
+
+        handle_cli_error(
+            logger,
+            title="API request failed",
+            message=f"The API request failed with status code {e.status_code}.",
+            suggestion="Please verify your `VELLUM_API_URL` environment variable is set correctly and try again.",
         )
 
     zip_buffer = io.BytesIO(zip_bytes)
@@ -231,10 +263,11 @@ def pull_command(
                         workflow_config.container_image_tag = "latest"
                 if not workflow_config.workflow_sandbox_id and pull_contents_metadata.workflow_sandbox_id:
                     workflow_config.workflow_sandbox_id = str(pull_contents_metadata.workflow_sandbox_id)
-                if not workflow_config.module and workflow_deployment and pull_contents_metadata.deployment_name:
-                    workflow_config.module = snake_case(pull_contents_metadata.deployment_name)
-                if not workflow_config.module and pull_contents_metadata.label:
-                    workflow_config.module = snake_case(pull_contents_metadata.label)
+                if not workflow_config.module:
+                    deployment_name = pull_contents_metadata.deployment_name if workflow_deployment else None
+                    workflow_config.module = create_module_name(
+                        deployment_name=deployment_name, label=pull_contents_metadata.label
+                    )
 
                 # Save or update the deployment info when pulling with --workflow-deployment
                 if workflow_deployment:
@@ -299,8 +332,11 @@ def pull_command(
                         logger.info(f"Writing to {target_file}...")
                         target.write(content)
     except zipfile.BadZipFile:
-        raise Exception(
-            "The API we tried to pull from returned an invalid zip file. Please make sure your `VELLUM_API_URL` environment variable is set correctly."  # noqa: E501
+        handle_cli_error(
+            logger,
+            title="Invalid response format",
+            message="The API returned an invalid zip file format.",
+            suggestion="Please verify your `VELLUM_API_URL` environment variable is set correctly and try again.",
         )
 
     if include_json: