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

vellum/workflows/utils/functions.py

@@ -1,17 +1,47 @@
 import dataclasses
+from datetime import datetime
 import inspect
-from typing import TYPE_CHECKING, Any, Callable, Optional, Type, Union, get_args, get_origin
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Callable,
+    ForwardRef,
+    List,
+    Literal,
+    Optional,
+    Type,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+)
 
 from pydantic import BaseModel
 from pydantic_core import PydanticUndefined
 from pydash import snake_case
 
+from vellum import Vellum
+from vellum.client.types.array_chat_message_content_item import ArrayChatMessageContentItem
 from vellum.client.types.function_definition import FunctionDefinition
+from vellum.workflows.constants import undefined
+from vellum.workflows.integrations.composio_service import ComposioService
+from vellum.workflows.integrations.mcp_service import MCPService
+from vellum.workflows.integrations.vellum_integration_service import VellumIntegrationService
+from vellum.workflows.types.core import is_json_type
+from vellum.workflows.types.definition import (
+    ComposioToolDefinition,
+    DeploymentDefinition,
+    MCPServer,
+    MCPToolDefinition,
+    VellumIntegrationToolDefinition,
+)
+from vellum.workflows.utils.vellum_variables import vellum_variable_type_to_openapi_type
 
 if TYPE_CHECKING:
     from vellum.workflows.workflows.base import BaseWorkflow
 
-type_map = {
+type_map: dict[Any, str] = {
     str: "string",
     int: "integer",
     float: "number",
@@ -21,52 +51,141 @@ type_map = {
     None: "null",
     type(None): "null",
     inspect._empty: "null",
+    "None": "null",
 }
 
+for k, v in list(type_map.items()):
+    if isinstance(k, type):
+        type_map[k.__name__] = v
 
-def _compile_annotation(annotation: Optional[Any], defs: dict[str, Any]) -> dict:
+
+def _get_def_name(annotation: Type) -> str:
+    return f"{annotation.__module__}.{annotation.__qualname__}"
+
+
+recorded_unions = {
+    ArrayChatMessageContentItem: "vellum.client.types.array_chat_message_content_item.ArrayChatMessageContentItem",
+}
+
+
+def compile_annotation(annotation: Optional[Any], defs: dict[str, Any]) -> dict:
     if annotation is None:
         return {"type": "null"}
 
+    if annotation is Any:
+        return {}
+
+    # Handle type variables (e.g., MapNodeItemType) - return empty schema since we can't determine the type
+    if isinstance(annotation, TypeVar):
+        return {}
+
+    if annotation is datetime:
+        return {"type": "string", "format": "date-time"}
+
     if get_origin(annotation) is Union:
-        return {"anyOf": [_compile_annotation(a, defs) for a in get_args(annotation)]}
+        if is_json_type(get_args(annotation)):
+            return {"$ref": "#/$defs/vellum.workflows.types.core.Json"}
+
+        if annotation in recorded_unions:
+            return {"$ref": f"#/$defs/{recorded_unions[annotation]}"}
+
+        # Filter out Type[undefined] from union args - it just makes the property optional
+        filtered_args = [
+            a
+            for a in get_args(annotation)
+            if not (get_origin(a) is type and get_args(a) and get_args(a)[0] is undefined)
+        ]
+
+        if len(filtered_args) == 0:
+            # Edge case: all union members were Type[undefined], return empty schema
+            return {}
+
+        if len(filtered_args) == 1:
+            return compile_annotation(filtered_args[0], defs)
+
+        return {"anyOf": [compile_annotation(a, defs) for a in filtered_args]}
+
+    if get_origin(annotation) is Literal:
+        values = list(get_args(annotation))
+        types = {type(value) for value in values}
+        if len(types) == 1:
+            value_type = types.pop()
+            if value_type in type_map:
+                return {"type": type_map[value_type], "enum": values}
+            else:
+                return {"enum": values}
+        else:
+            return {"enum": values}
 
     if get_origin(annotation) is dict:
         _, value_type = get_args(annotation)
-        return {"type": "object", "additionalProperties": _compile_annotation(value_type, defs)}
+        return {"type": "object", "additionalProperties": compile_annotation(value_type, defs)}
 
     if get_origin(annotation) is list:
         item_type = get_args(annotation)[0]
-        return {"type": "array", "items": _compile_annotation(item_type, defs)}
+        return {"type": "array", "items": compile_annotation(item_type, defs)}
 
-    if dataclasses.is_dataclass(annotation):
-        if annotation.__name__ not in defs:
+    if get_origin(annotation) is tuple:
+        args = get_args(annotation)
+        if len(args) == 2 and args[1] is Ellipsis:
+            # Tuple[int, ...] with homogeneous items
+            return {"type": "array", "items": compile_annotation(args[0], defs)}
+        else:
+            # Tuple[int, str] with fixed length items
+            result = {
+                "type": "array",
+                "prefixItems": [compile_annotation(arg, defs) for arg in args],
+                "minItems": len(args),
+                "maxItems": len(args),
+            }
+            return result
+
+    if dataclasses.is_dataclass(annotation) and isinstance(annotation, type):
+        def_name = _get_def_name(annotation)
+        if def_name not in defs:
             properties = {}
             required = []
             for field in dataclasses.fields(annotation):
-                properties[field.name] = _compile_annotation(field.type, defs)
+                properties[field.name] = compile_annotation(field.type, defs)
                 if field.default is dataclasses.MISSING:
                     required.append(field.name)
                 else:
                     properties[field.name]["default"] = _compile_default_value(field.default)
-            defs[annotation.__name__] = {"type": "object", "properties": properties, "required": required}
-        return {"$ref": f"#/$defs/{annotation.__name__}"}
+            defs[def_name] = {"type": "object", "properties": properties, "required": required}
+        return {"$ref": f"#/$defs/{def_name}"}
 
-    if issubclass(annotation, BaseModel):
-        if annotation.__name__ not in defs:
+    if inspect.isclass(annotation) and issubclass(annotation, BaseModel):
+        def_name = _get_def_name(annotation)
+        if def_name not in defs:
             properties = {}
             required = []
-            for field_name, field in annotation.model_fields.items():
-                # Mypy is incorrect here, the `annotation` attribute is defined on `FieldInfo`
-                field_annotation = field.annotation  # type: ignore[attr-defined]
-                properties[field_name] = _compile_annotation(field_annotation, defs)
-                if field.default is PydanticUndefined:
+            for field_name, field_info in annotation.model_fields.items():
+                # field_info is a FieldInfo object which has an annotation attribute
+                properties[field_name] = compile_annotation(field_info.annotation, defs)
+
+                if field_info.description is not None:
+                    properties[field_name]["description"] = field_info.description
+
+                if field_info.default is PydanticUndefined:
                     required.append(field_name)
                 else:
-                    properties[field_name]["default"] = _compile_default_value(field.default)
-            defs[annotation.__name__] = {"type": "object", "properties": properties, "required": required}
+                    properties[field_name]["default"] = _compile_default_value(field_info.default)
+            defs[def_name] = {"type": "object", "properties": properties, "required": required}
+
+        return {"$ref": f"#/$defs/{def_name}"}
+
+    if type(annotation) is ForwardRef:
+        # Ignore forward references for now
+        return {}
 
-        return {"$ref": f"#/$defs/{annotation.__name__}"}
+    # Handle Type[undefined] - skip it as it just makes the property optional
+    if get_origin(annotation) is type:
+        args = get_args(annotation)
+        if args and args[0] is undefined:
+            return {}
+
+    if annotation not in type_map:
+        raise ValueError(f"Failed to compile type: {annotation}")
 
     return {"type": type_map[annotation]}
 
@@ -80,15 +199,31 @@ def _compile_default_value(default: Any) -> Any:
     if isinstance(default, BaseModel):
         return {
             field_name: _compile_default_value(getattr(default, field_name))
-            for field_name in default.model_fields.keys()
+            for field_name in default.__class__.model_fields.keys()
         }
 
     return default
 
 
+def _compile_workflow_deployment_input(input_var: Any) -> dict[str, Any]:
+    """
+    Converts a deployment workflow input variable to a JSON schema type definition.
+    """
+    primitive_type = vellum_variable_type_to_openapi_type(input_var.type)
+    input_schema = {"type": primitive_type}
+
+    if input_var.default is not None:
+        input_schema["default"] = input_var.default.value
+
+    return input_schema
+
+
 def compile_function_definition(function: Callable) -> FunctionDefinition:
     """
     Converts a Python function into our Vellum-native FunctionDefinition type.
+
+    Args:
+        function: The Python function to compile
     """
 
     try:
@@ -96,11 +231,32 @@ def compile_function_definition(function: Callable) -> FunctionDefinition:
     except ValueError as e:
         raise ValueError(f"Failed to get signature for function {function.__name__}: {str(e)}")
 
+    # Get inputs from the decorator if present
+    inputs = getattr(function, "__vellum_inputs__", {})
+    examples = getattr(function, "__vellum_examples__", None)
+    exclude_params = set(inputs.keys())
+
     properties = {}
     required = []
     defs: dict[str, Any] = {}
     for param in signature.parameters.values():
-        properties[param.name] = _compile_annotation(param.annotation, defs)
+        # Skip parameters that are in the exclude_params set
+        if exclude_params and param.name in exclude_params:
+            continue
+
+        # Check if parameter uses Annotated type hint
+        if get_origin(param.annotation) is Annotated:
+            args = get_args(param.annotation)
+            actual_type = args[0]
+            # Extract description from metadata
+            description = args[1] if len(args) > 1 and isinstance(args[1], str) else None
+
+            properties[param.name] = compile_annotation(actual_type, defs)
+            if description:
+                properties[param.name]["description"] = description
+        else:
+            properties[param.name] = compile_annotation(param.annotation, defs)
+
         if param.default is inspect.Parameter.empty:
             required.append(param.name)
         else:
@@ -109,6 +265,8 @@ def compile_function_definition(function: Callable) -> FunctionDefinition:
     parameters = {"type": "object", "properties": properties, "required": required}
     if defs:
         parameters["$defs"] = defs
+    if examples is not None:
+        parameters["examples"] = examples
 
     return FunctionDefinition(
         name=function.__name__,
@@ -117,7 +275,7 @@ def compile_function_definition(function: Callable) -> FunctionDefinition:
     )
 
 
-def compile_workflow_function_definition(workflow_class: Type["BaseWorkflow"]) -> FunctionDefinition:
+def compile_inline_workflow_function_definition(workflow_class: Type["BaseWorkflow"]) -> FunctionDefinition:
     """
     Converts a base workflow class into our Vellum-native FunctionDefinition type.
     """
@@ -125,6 +283,11 @@ def compile_workflow_function_definition(workflow_class: Type["BaseWorkflow"]) -
     inputs_class = workflow_class.get_inputs_class()
     vars_inputs_class = vars(inputs_class)
 
+    # Get inputs from the decorator if present (to exclude from schema)
+    inputs = getattr(workflow_class, "__vellum_inputs__", {})
+    examples = getattr(workflow_class, "__vellum_examples__", None)
+    exclude_params = set(inputs.keys())
+
     properties = {}
     required = []
     defs: dict[str, Any] = {}
@@ -133,7 +296,11 @@ def compile_workflow_function_definition(workflow_class: Type["BaseWorkflow"]) -
         if name.startswith("__"):
             continue
 
-        properties[name] = _compile_annotation(field_type, defs)
+        # Skip parameters that are in the exclude_params set
+        if exclude_params and name in exclude_params:
+            continue
+
+        properties[name] = compile_annotation(field_type, defs)
 
         # Check if the field has a default value
         if name not in vars_inputs_class:
@@ -145,9 +312,203 @@ def compile_workflow_function_definition(workflow_class: Type["BaseWorkflow"]) -
     parameters = {"type": "object", "properties": properties, "required": required}
     if defs:
         parameters["$defs"] = defs
+    if examples is not None:
+        parameters["examples"] = examples
 
     return FunctionDefinition(
         name=snake_case(workflow_class.__name__),
         description=workflow_class.__doc__,
         parameters=parameters,
     )
+
+
+def compile_workflow_deployment_function_definition(
+    deployment_definition: DeploymentDefinition,
+    vellum_client: Vellum,
+) -> FunctionDefinition:
+    """
+    Converts a deployment workflow config into our Vellum-native FunctionDefinition type.
+
+    Args:
+        deployment_definition: DeploymentDefinition instance
+        vellum_client: Vellum client instance
+    """
+    release_info = deployment_definition.get_release_info(vellum_client)
+
+    name = release_info["name"]
+    description = release_info["description"]
+    input_variables = release_info["input_variables"]
+
+    properties = {}
+    required = []
+
+    for input_var in input_variables:
+        properties[input_var.key] = _compile_workflow_deployment_input(input_var)
+
+        if input_var.required and input_var.default is None:
+            required.append(input_var.key)
+
+    parameters = {"type": "object", "properties": properties, "required": required}
+
+    return FunctionDefinition(
+        name=name.replace("-", ""),
+        description=description,
+        parameters=parameters,
+    )
+
+
+def get_mcp_tool_name(tool_def: MCPToolDefinition) -> str:
+    """Generate a unique name for an MCP tool by combining server and tool names."""
+    server_name = snake_case(tool_def.server.name)
+    return f"{server_name}__{tool_def.name}"
+
+
+def compile_mcp_tool_definition(server_def: MCPServer) -> List[MCPToolDefinition]:
+    """Hydrate an MCPToolDefinition with detailed information from the MCP server.
+
+    We do tool discovery on the MCP server to get the tool definitions.
+
+    Args:
+        server_def: The basic MCPToolDefinition to enhance
+
+    Returns:
+        MCPToolDefinition with detailed parameters and description
+    """
+    try:
+        mcp_service = MCPService()
+        return mcp_service.hydrate_tool_definitions(server_def)
+    except Exception:
+        return []
+
+
+def compile_composio_tool_definition(tool_def: ComposioToolDefinition) -> FunctionDefinition:
+    """Hydrate a ComposioToolDefinition with detailed information from the Composio API.
+
+    Args:
+        tool_def: The basic ComposioToolDefinition to enhance
+
+    Returns:
+        FunctionDefinition with detailed parameters and description
+    """
+    try:
+        composio_service = ComposioService()
+        tool_details = composio_service.get_tool_by_slug(tool_def.action)
+
+        # Create a FunctionDefinition directly with proper field extraction
+        return FunctionDefinition(
+            name=tool_def.name,
+            description=tool_details.get("description", tool_def.description),
+            parameters=tool_details.get("input_parameters", {}),
+        )
+    except Exception:
+        # If hydration fails (including no API key), return basic function definition
+        return FunctionDefinition(
+            name=tool_def.name,
+            description=tool_def.description,
+            parameters={},
+        )
+
+
+def compile_vellum_integration_tool_definition(
+    tool_def: VellumIntegrationToolDefinition,
+    vellum_client: Vellum,
+) -> FunctionDefinition:
+    """Compile a VellumIntegrationToolDefinition into a FunctionDefinition.
+
+    Args:
+        tool_def: The VellumIntegrationToolDefinition to compile
+        vellum_client: Vellum client instance
+
+    Returns:
+        FunctionDefinition with tool parameters and description
+    """
+    try:
+        service = VellumIntegrationService(vellum_client)
+        tool_details = service.get_tool_definition(
+            integration=tool_def.integration_name,
+            provider=tool_def.provider.value,
+            tool_name=tool_def.name,
+            toolkit_version=tool_def.toolkit_version,
+        )
+
+        return FunctionDefinition(
+            name=tool_def.name,
+            description=tool_details.description,
+            parameters=tool_details.parameters or {},
+        )
+    except Exception:
+        # Fallback for service failures
+        return FunctionDefinition(name=tool_def.name, description=tool_def.description, parameters={})
+
+
+ToolType = Union[Callable[..., Any], Type["BaseWorkflow"]]
+
+
+def tool(
+    *,
+    inputs: Optional[dict[str, Any]] = None,
+    examples: Optional[List[dict[str, Any]]] = None,
+) -> Callable[[ToolType], ToolType]:
+    """
+    Decorator to configure a tool function or inline workflow.
+
+    Currently supports specifying which parameters should come from parent workflow inputs
+    via the `inputs` mapping. Also supports providing `examples` which will be hoisted
+    into the JSON Schema `examples` keyword for this tool's parameters.
+
+    Args:
+        inputs: Mapping of parameter names to parent input references
+        examples: List of example argument objects for the tool
+
+    Example with function:
+        @tool(inputs={
+            "parent_input": ParentInputs.parent_input,
+        }, examples=[{"location": "San Francisco"}])
+        def get_string(parent_input: str, user_query: str) -> str:
+            return f"Parent: {parent_input}, Query: {user_query}"
+
+    Example with inline workflow:
+        @tool(inputs={
+            "context": ParentInputs.context,
+        })
+        class MyInlineWorkflow(BaseWorkflow):
+            graph = MyNode
+
+            class Outputs(BaseWorkflow.Outputs):
+                result = MyNode.Outputs.result
+    """
+
+    def decorator(func: ToolType) -> ToolType:
+        # Store the inputs mapping on the function/workflow for later use
+        if inputs is not None:
+            setattr(func, "__vellum_inputs__", inputs)
+        # Store the examples on the function/workflow for later use
+        if examples is not None:
+            setattr(func, "__vellum_examples__", examples)
+        return func
+
+    return decorator
+
+
+def use_tool_inputs(**inputs: Any) -> Callable[[Callable], Callable]:
+    """
+    Decorator to specify which parameters of a tool function should be provided
+    from the parent workflow inputs rather than from the LLM.
+
+    .. deprecated:: 2.0.0
+        This function is deprecated and will be removed in version 2.0.0.
+        Use :func:`tool` with the ``inputs`` parameter instead.
+
+    This is a backward-compatible helper equivalent to @tool(inputs={...}).
+
+    Args:
+        **inputs: Mapping of parameter names to parent input references
+
+    Example:
+        @use_tool_inputs(
+            parent_input=ParentInputs.parent_input,
+        )
+        def get_string(parent_input: str, user_query: str) -> str:
+            return f"Parent: {parent_input}, Query: {user_query}"
+    """
+    return tool(inputs=inputs)

vellum/workflows/utils/hmac.py

@@ -0,0 +1,44 @@
+import hashlib
+import hmac
+import os
+import time
+
+from requests import PreparedRequest
+
+
+def _sign_request(request: PreparedRequest, secret: str) -> None:
+    """
+    Sign a request with HMAC using the same pattern as Django implementation.
+
+    Args:
+        request: The prepared request to sign
+        secret: The HMAC secret string
+    """
+    timestamp = str(int(time.time()))
+
+    body = request.body or b""
+    if isinstance(body, str):
+        body = body.encode()
+
+    message = f"{timestamp}\n{request.method}\n{request.url}\n".encode() + body
+
+    signature = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
+
+    hmac_headers = {
+        "X-Vellum-Timestamp": timestamp,
+        "X-Vellum-Signature": signature,
+    }
+
+    request.headers.update(hmac_headers)
+
+
+def sign_request_with_env_secret(request: PreparedRequest) -> None:
+    """
+    Sign a request using VELLUM_HMAC_SECRET environment variable if available.
+
+    Args:
+        request: The prepared request to sign
+    """
+    hmac_secret = os.environ.get("VELLUM_HMAC_SECRET")
+    if hmac_secret:
+        _sign_request(request, hmac_secret)

vellum/workflows/utils/names.py

@@ -1,13 +1,41 @@
 import re
+from typing import Optional
+
+from pydash import snake_case
 
 
 def pascal_to_title_case(pascal_str: str) -> str:
-    # Insert space before each capital letter (except the first one)
-    title_case_str = re.sub(r"(?<!^)(?=[A-Z])", " ", pascal_str)
+    title_case_str = re.sub(r"(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])", " ", pascal_str)
+
+    words = title_case_str.split()
+    result_words = []
 
-    # Return the result in title case
-    return title_case_str.title()
+    for word in words:
+        if word.isupper():
+            result_words.append(word)
+        # Otherwise, apply title case
+        else:
+            result_words.append(word.capitalize())
+
+    return " ".join(result_words)
 
 
 def snake_to_title_case(snake_str: str) -> str:
     return pascal_to_title_case(snake_str.replace("_", " "))
+
+
+def create_module_name(*, deployment_name: Optional[str] = None, label: Optional[str] = None) -> str:
+    """Create a module name from potential workflow metadata.
+
+    Args:
+        deployment_name: Optional deployment name to convert to snake_case
+        label: Optional label to convert to snake_case (fallback if deployment_name not provided)
+
+    Returns:
+        Module name in valid python syntax, or empty string if unable to resolve one based on the arguments
+    """
+    if deployment_name:
+        return snake_case(deployment_name)
+    elif label:
+        return snake_case(label)
+    return ""

vellum/workflows/utils/pydantic_schema.py

@@ -0,0 +1,56 @@
+import inspect
+from typing import Any, Dict, Type, TypeVar
+
+import pydantic
+from pydantic import BaseModel
+
+from vellum.workflows.utils.functions import compile_annotation
+
+T = TypeVar("T")
+IS_PYDANTIC_V2 = pydantic.VERSION.startswith("2.")
+_type_adapter_cache: Dict[Type, "pydantic.TypeAdapter"] = {}  # type: ignore[type-arg]
+
+
+def validate_obj_as(type_: Type[T], object_: Any) -> T:
+    """Validate an object as a given type using pydantic's TypeAdapter (v2) or parse_obj_as (v1).
+
+    This is similar to parse_obj_as but without the convert_and_respect_annotation_metadata step,
+    making it suitable for simple type validation without annotation metadata handling.
+    """
+    if IS_PYDANTIC_V2:
+        if type_ not in _type_adapter_cache:
+            _type_adapter_cache[type_] = pydantic.TypeAdapter(type_)  # type: ignore[attr-defined]
+        return _type_adapter_cache[type_].validate_python(object_)
+    return pydantic.parse_obj_as(type_, object_)  # type: ignore[attr-defined]
+
+
+def normalize_json(schema_input: Any) -> Any:
+    """
+    Recursively normalize JSON data by converting Pydantic models to JSON schema.
+
+    This function processes dictionaries recursively to find and convert any
+    Pydantic model classes or instances to their JSON schema representation.
+
+    Args:
+        schema_input: Can be a Pydantic model class, instance, dict, or any other value
+
+    Returns:
+        Normalized JSON data with Pydantic models converted to JSON schema
+    """
+    if isinstance(schema_input, dict):
+        return {key: normalize_json(value) for key, value in schema_input.items()}
+
+    if inspect.isclass(schema_input) and issubclass(schema_input, BaseModel):
+        defs: Dict[str, Any] = {}
+        result = compile_annotation(schema_input, defs)
+
+        if "$ref" in result and defs:
+            ref_name = result["$ref"].split("/")[-1]
+            if ref_name in defs:
+                return defs[ref_name]
+
+        return result
+    elif isinstance(schema_input, BaseModel):
+        return {key: normalize_json(getattr(schema_input, key)) for key in schema_input.__class__.model_fields.keys()}
+    else:
+        return schema_input