vellum-ai 1.8.2__py3-none-any.whl → 1.8.4__py3-none-any.whl

vellum/workflows/runner/runner.py

@@ -74,6 +74,9 @@ from vellum.workflows.references import ExternalInputReference, OutputReference
 from vellum.workflows.references.state_value import StateValueReference
 from vellum.workflows.state.base import BaseState
 from vellum.workflows.state.delta import StateDelta
+from vellum.workflows.triggers.base import BaseTrigger
+from vellum.workflows.triggers.integration import IntegrationTrigger
+from vellum.workflows.triggers.manual import ManualTrigger
 from vellum.workflows.types.core import CancelSignal
 from vellum.workflows.types.generics import InputsType, OutputsType, StateType
 
@@ -109,6 +112,7 @@ class WorkflowRunner(Generic[StateType]):
         max_concurrency: Optional[int] = None,
         timeout: Optional[float] = None,
         init_execution_context: Optional[ExecutionContext] = None,
+        trigger: Optional[BaseTrigger] = None,
     ):
         if state and external_inputs:
             raise ValueError("Can only run a Workflow providing one of state or external inputs, not both")
@@ -198,7 +202,24 @@ class WorkflowRunner(Generic[StateType]):
                 )
 
             self._entrypoints = self.workflow.get_entrypoints()
+        elif trigger:
+            # When trigger is provided, set up default state and filter entrypoints by trigger type
+            normalized_inputs = deepcopy(inputs) if inputs else self.workflow.get_default_inputs()
+            if state:
+                self._initial_state = deepcopy(state)
+                self._initial_state.meta.workflow_inputs = normalized_inputs
+                self._initial_state.meta.span_id = uuid4()
+                self._initial_state.meta.workflow_definition = self.workflow.__class__
+            else:
+                self._initial_state = self.workflow.get_default_state(normalized_inputs)
+                self._should_emit_initial_state = False
+
+            # Validate and bind trigger, then filter entrypoints
+            self._validate_and_bind_trigger(trigger)
+            self._entrypoints = self.workflow.get_entrypoints()
+            self._filter_entrypoints_for_trigger(trigger)
         else:
+            # Default case: no entrypoint overrides and no trigger
             normalized_inputs = deepcopy(inputs) if inputs else self.workflow.get_default_inputs()
             if state:
                 self._initial_state = deepcopy(state)
@@ -213,6 +234,9 @@ class WorkflowRunner(Generic[StateType]):
                 self._should_emit_initial_state = False
             self._entrypoints = self.workflow.get_entrypoints()
 
+            # Check if workflow requires a trigger but none was provided
+            self._validate_no_trigger_provided()
+
         # This queue is responsible for sending events from WorkflowRunner to the outside world
         self._workflow_event_outer_queue: Queue[WorkflowEvent] = Queue()
 
@@ -250,6 +274,126 @@ class WorkflowRunner(Generic[StateType]):
         self._cancel_thread: Optional[Thread] = None
         self._timeout_thread: Optional[Thread] = None
 
+    def _has_manual_trigger(self) -> bool:
+        """Check if workflow has ManualTrigger."""
+        for subgraph in self.workflow.get_subgraphs():
+            for trigger in subgraph.triggers:
+                if issubclass(trigger, ManualTrigger):
+                    return True
+        return False
+
+    def _get_entrypoints_for_trigger_type(self, trigger_class: Type) -> List[Type[BaseNode]]:
+        """Get all entrypoints connected to a specific trigger type.
+
+        Allows subclasses: if trigger_class is a subclass of any declared trigger,
+        returns those entrypoints.
+        """
+        entrypoints: List[Type[BaseNode]] = []
+        for subgraph in self.workflow.get_subgraphs():
+            for trigger in subgraph.triggers:
+                # Check if the provided trigger_class is a subclass of the declared trigger
+                # This allows runtime instances to be subclasses of what's declared in the workflow
+                if issubclass(trigger_class, trigger):
+                    entrypoints.extend(subgraph.entrypoints)
+        return entrypoints
+
+    def _validate_and_bind_trigger(self, trigger: BaseTrigger) -> None:
+        """
+        Validate that trigger is compatible with workflow and bind it to state.
+
+        Supports all trigger types derived from BaseTrigger:
+        - IntegrationTrigger instances (Slack, Gmail, etc.)
+        - ManualTrigger instances (explicit manual execution)
+        - ScheduledTrigger instances (time-based triggers)
+        - Any future trigger types
+
+        Raises:
+            WorkflowInitializationException: If trigger type is not compatible with workflow
+        """
+        trigger_class = type(trigger)
+
+        # Search for a compatible trigger type in the workflow
+        found_compatible_trigger = False
+        has_any_triggers = False
+        incompatible_trigger_names: List[str] = []
+
+        for subgraph in self.workflow.get_subgraphs():
+            for declared_trigger in subgraph.triggers:
+                has_any_triggers = True
+                # Allow subclasses: if workflow declares BaseSlackTrigger, accept SpecificSlackTrigger instances
+                if issubclass(trigger_class, declared_trigger):
+                    found_compatible_trigger = True
+                    break
+                else:
+                    incompatible_trigger_names.append(declared_trigger.__name__)
+
+            if found_compatible_trigger:
+                break
+
+        # Special case: workflows with no explicit triggers implicitly support ManualTrigger
+        if not has_any_triggers and not isinstance(trigger, ManualTrigger):
+            raise WorkflowInitializationException(
+                message=f"Provided trigger type {trigger_class.__name__} is not compatible with workflow. "
+                f"Workflow has no explicit triggers and only supports ManualTrigger.",
+                workflow_definition=self.workflow.__class__,
+                code=WorkflowErrorCode.INVALID_INPUTS,
+            )
+
+        # Validate that we found a compatible trigger type
+        if has_any_triggers and not found_compatible_trigger:
+            raise WorkflowInitializationException(
+                message=f"Provided trigger type {trigger_class.__name__} is not compatible with workflow triggers. "
+                f"Workflow has: {sorted(set(incompatible_trigger_names))}",
+                workflow_definition=self.workflow.__class__,
+                code=WorkflowErrorCode.INVALID_INPUTS,
+            )
+
+        # Bind trigger to state (works for all trigger types via BaseTrigger.bind_to_state)
+        trigger.bind_to_state(self._initial_state)
+
+    def _filter_entrypoints_for_trigger(self, trigger: BaseTrigger) -> None:
+        """
+        Filter entrypoints to those connected to the specific trigger type.
+
+        Uses the specific trigger subclass, not the parent class, allowing workflows
+        with multiple triggers to route to the correct path.
+        """
+        trigger_class = type(trigger)
+        specific_entrypoints = self._get_entrypoints_for_trigger_type(trigger_class)
+        if specific_entrypoints:
+            self._entrypoints = specific_entrypoints
+
+    def _validate_no_trigger_provided(self) -> None:
+        """
+        Validate that workflow can run without a trigger.
+
+        If workflow has IntegrationTrigger(s) but no ManualTrigger, it requires a trigger instance.
+        If workflow has both, filter entrypoints to ManualTrigger path only.
+
+        Raises:
+            WorkflowInitializationException: If workflow requires trigger but none was provided
+        """
+        # Collect all IntegrationTrigger types in the workflow
+        workflow_integration_triggers = []
+        for subgraph in self.workflow.get_subgraphs():
+            for trigger_type in subgraph.triggers:
+                if issubclass(trigger_type, IntegrationTrigger):
+                    workflow_integration_triggers.append(trigger_type)
+
+        if workflow_integration_triggers:
+            if not self._has_manual_trigger():
+                # Workflow has ONLY IntegrationTrigger - this is an error
+                raise WorkflowInitializationException(
+                    message="Workflow has IntegrationTrigger which requires trigger parameter",
+                    workflow_definition=self.workflow.__class__,
+                    code=WorkflowErrorCode.INVALID_INPUTS,
+                )
+
+            # Workflow has both IntegrationTrigger and ManualTrigger - filter to ManualTrigger path
+            manual_entrypoints = self._get_entrypoints_for_trigger_type(ManualTrigger)
+            if manual_entrypoints:
+                self._entrypoints = manual_entrypoints
+
     @contextmanager
     def _httpx_logger_with_span_id(self) -> Iterator[None]:
         """

vellum/workflows/state/context.py

@@ -1,7 +1,8 @@
+from dataclasses import dataclass
 from functools import cached_property
 from queue import Queue
 from uuid import UUID, uuid4
-from typing import TYPE_CHECKING, Dict, List, Optional, Type
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Type
 
 from vellum import Vellum, __version__
 from vellum.workflows.context import ExecutionContext, get_execution_context, set_execution_context
@@ -9,6 +10,7 @@ from vellum.workflows.events.types import ExternalParentContext
 from vellum.workflows.nodes.mocks import MockNodeExecution, MockNodeExecutionArg
 from vellum.workflows.outputs.base import BaseOutputs
 from vellum.workflows.references.constant import ConstantValueReference
+from vellum.workflows.state.store import Store
 from vellum.workflows.utils.uuids import generate_workflow_deployment_prefix
 from vellum.workflows.utils.zip import extract_zip_files
 from vellum.workflows.vellum_client import create_vellum_client
@@ -19,6 +21,18 @@ if TYPE_CHECKING:
     from vellum.workflows.workflows.base import BaseWorkflow
 
 
+@dataclass
+class WorkflowDeploymentMetadata:
+    """Metadata about a workflow deployment needed for parent context construction."""
+
+    deployment_id: UUID
+    deployment_name: str
+    deployment_history_item_id: UUID
+    release_tag_id: UUID
+    release_tag_name: str
+    workflow_version_id: UUID
+
+
 class WorkflowContext:
     def __init__(
         self,
@@ -27,12 +41,14 @@ class WorkflowContext:
         execution_context: Optional[ExecutionContext] = None,
         generated_files: Optional[dict[str, str]] = None,
         namespace: Optional[str] = None,
+        store_class: Optional[Type[Store]] = None,
     ):
         self._vellum_client = vellum_client
         self._event_queue: Optional[Queue["WorkflowEvent"]] = None
         self._node_output_mocks_map: Dict[Type[BaseOutputs], List[MockNodeExecution]] = {}
         self._execution_context = get_execution_context()
         self._namespace = namespace
+        self._store_class = store_class if store_class is not None else Store
 
         if execution_context is not None:
             self._execution_context.trace_id = execution_context.trace_id
@@ -72,6 +88,10 @@ class WorkflowContext:
     def node_output_mocks_map(self) -> Dict[Type[BaseOutputs], List[MockNodeExecution]]:
         return self._node_output_mocks_map
 
+    @property
+    def store_class(self) -> Type[Store]:
+        return self._store_class
+
     @property
     def monitoring_url(self) -> Optional[str]:
         """
@@ -148,7 +168,7 @@ class WorkflowContext:
 
     def resolve_workflow_deployment(
         self, deployment_name: str, release_tag: str, state: "BaseState"
-    ) -> Optional["BaseWorkflow"]:
+    ) -> Optional[Tuple[Type["BaseWorkflow"], Optional[WorkflowDeploymentMetadata]]]:
         """
         Resolve a workflow deployment by name and release tag.
 
@@ -158,20 +178,22 @@ class WorkflowContext:
             state: The base state to pass to the workflow
 
         Returns:
-            BaseWorkflow instance if found, None otherwise
+            Tuple of (BaseWorkflow class, deployment metadata) if found
         """
         if not self._generated_files or not self._namespace:
             return None
 
         expected_prefix = generate_workflow_deployment_prefix(deployment_name, release_tag)
 
+        deployment_metadata = self._fetch_deployment_metadata(deployment_name, release_tag)
+
         try:
             from vellum.workflows.workflows.base import BaseWorkflow
 
             WorkflowClass = BaseWorkflow.load_from_module(f"{self.namespace}.{expected_prefix}")
             WorkflowClass.is_dynamic = True
-            workflow_instance = WorkflowClass(context=WorkflowContext.create_from(self), parent_state=state)
-            return workflow_instance
+            # Return the class, not an instance, so caller can instantiate within proper execution context
+            return (WorkflowClass, deployment_metadata)
         except Exception:
             pass
 
@@ -200,16 +222,61 @@ class WorkflowContext:
 
             WorkflowClass = BaseWorkflow.load_from_module(f"{self.namespace}.{expected_prefix}")
             WorkflowClass.is_dynamic = True
-            workflow_instance = WorkflowClass(context=WorkflowContext.create_from(self), parent_state=state)
-            return workflow_instance
+            # Return the class, not an instance, so caller can instantiate within proper execution context
+            return (WorkflowClass, deployment_metadata)
 
         except Exception:
             pass
 
         return None
 
+    def _fetch_deployment_metadata(
+        self, deployment_name: str, release_tag: str
+    ) -> Optional[WorkflowDeploymentMetadata]:
+        """
+        Fetch deployment metadata from the Vellum API.
+
+        Args:
+            deployment_name: The name of the workflow deployment
+            release_tag: The release tag name
+
+        Returns:
+            WorkflowDeploymentMetadata if successful, None otherwise
+        """
+        try:
+            # Fetch deployment details
+            deployment = self.vellum_client.workflow_deployments.retrieve(deployment_name)
+
+            deployment_id = UUID(deployment.id)
+
+            # Fetch release tag details
+            release_tag_info = self.vellum_client.workflow_deployments.retrieve_workflow_release_tag(
+                deployment.id, release_tag
+            )
+
+            # Fetch workflow version
+            release = self.vellum_client.workflow_deployments.retrieve_workflow_deployment_release(
+                str(deployment_id), release_tag
+            )
+
+            return WorkflowDeploymentMetadata(
+                deployment_id=deployment_id,
+                deployment_name=deployment.name,
+                deployment_history_item_id=UUID(deployment.last_deployed_history_item_id),
+                release_tag_id=UUID(release_tag_info.release.id),
+                release_tag_name=release_tag_info.name,
+                workflow_version_id=UUID(release.workflow_version.id),
+            )
+        except Exception:
+            # If we fail to fetch metadata, return None - the workflow can still run
+            # but won't have the full parent context hierarchy
+            return None
+
     @classmethod
     def create_from(cls, context):
         return cls(
-            vellum_client=context.vellum_client, generated_files=context.generated_files, namespace=context.namespace
+            vellum_client=context.vellum_client,
+            generated_files=context.generated_files,
+            namespace=context.namespace,
+            store_class=context.store_class,
         )

vellum/workflows/workflows/base.py

@@ -79,6 +79,7 @@ from vellum.workflows.runner.runner import ExternalInputsArg, RunFromNodeArg
 from vellum.workflows.state.base import BaseState, StateMeta
 from vellum.workflows.state.context import WorkflowContext
 from vellum.workflows.state.store import Store
+from vellum.workflows.triggers.base import BaseTrigger
 from vellum.workflows.types import CancelSignal
 from vellum.workflows.types.generics import InputsType, StateType
 from vellum.workflows.types.utils import get_original_base
@@ -256,7 +257,9 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         self._context = context or WorkflowContext()
         self.emitters = emitters or (self.emitters if hasattr(self, "emitters") else [])
         self.resolvers = resolvers or (self.resolvers if hasattr(self, "resolvers") else [])
-        self._store = store or Store()
+        # Prioritize store type from WorkflowContext to allow subworkflows to inherit EmptyStore
+        # TODO(v2.0.0): Remove the concept of an internal store altogether (important-comment)
+        self._store = store or self._context.store_class()
         self._execution_context = self._context.execution_context
         self._current_runner: Optional[WorkflowRunner] = None
 
@@ -382,6 +385,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         node_output_mocks: Optional[MockNodeExecutionArg] = None,
         max_concurrency: Optional[int] = None,
         timeout: Optional[float] = None,
+        trigger: Optional[BaseTrigger] = None,
     ) -> TerminalWorkflowEvent:
         """
         Invoke a Workflow, returning the last event emitted, which should be one of:
@@ -422,6 +426,12 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         timeout: Optional[float] = None
             The maximum time in seconds to allow the Workflow to run. If the timeout is exceeded, the Workflow
             will be rejected with a WORKFLOW_TIMEOUT error code and any nodes in flight will be rejected.
+
+        trigger: Optional[BaseTrigger] = None
+            A trigger instance for workflows with triggers (e.g., IntegrationTrigger, ManualTrigger, ScheduledTrigger).
+            The trigger instance is bound to the workflow state, making its attributes accessible to downstream nodes.
+            Required for workflows that only have IntegrationTrigger; optional for workflows with both ManualTrigger
+            and IntegrationTrigger.
         """
 
         runner = WorkflowRunner(
@@ -436,6 +446,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
             max_concurrency=max_concurrency,
             timeout=timeout,
             init_execution_context=self._execution_context,
+            trigger=trigger,
         )
         self._current_runner = runner
         events = runner.stream()
@@ -507,6 +518,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         node_output_mocks: Optional[MockNodeExecutionArg] = None,
         max_concurrency: Optional[int] = None,
         timeout: Optional[float] = None,
+        trigger: Optional[BaseTrigger] = None,
     ) -> WorkflowEventStream:
         """
         Invoke a Workflow, yielding events as they are emitted.
@@ -548,6 +560,12 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
         timeout: Optional[float] = None
             The maximum time in seconds to allow the Workflow to run. If the timeout is exceeded, the Workflow
             will be rejected with a WORKFLOW_TIMEOUT error code and any nodes in flight will be rejected.
+
+        trigger: Optional[BaseTrigger] = None
+            A trigger instance for workflows with triggers (e.g., IntegrationTrigger, ManualTrigger, ScheduledTrigger).
+            The trigger instance is bound to the workflow state, making its attributes accessible to downstream nodes.
+            Required for workflows that only have IntegrationTrigger; optional for workflows with both ManualTrigger
+            and IntegrationTrigger.
         """
 
         should_yield = event_filter or workflow_event_filter
@@ -563,6 +581,7 @@ class BaseWorkflow(Generic[InputsType, StateType], BaseExecutable, metaclass=_Ba
             max_concurrency=max_concurrency,
             timeout=timeout,
             init_execution_context=self._execution_context,
+            trigger=trigger,
         )
         self._current_runner = runner
         runner_stream = runner.stream()

vellum/workflows/workflows/event_filters.py

@@ -52,5 +52,18 @@ def root_workflow_event_filter(workflow_definition: Type["BaseWorkflow"], event:
     return event_parent_definition.model_dump() == current_workflow_definition.model_dump()
 
 
+def workflow_sandbox_event_filter(workflow_definition: Type["BaseWorkflow"], event: "WorkflowEvent") -> bool:
+    """
+    Filter designed for Workflow Sandbox interfaces: include all events except
+    workflow.execution.snapshotted events from nested/subworkflows. Only allow
+    snapshotted events when they belong to the root workflow definition.
+    """
+
+    if event.name == "workflow.execution.snapshotted":
+        return event.workflow_definition == workflow_definition
+
+    return True
+
+
 def all_workflow_event_filter(workflow_definition: Type["BaseWorkflow"], event: "WorkflowEvent") -> bool:
     return True

vellum/workflows/workflows/tests/test_event_filters.py

@@ -0,0 +1,126 @@
+from vellum.workflows.inputs import BaseInputs
+from vellum.workflows.nodes import BaseNode, InlineSubworkflowNode
+from vellum.workflows.outputs.base import BaseOutputs
+from vellum.workflows.state.base import BaseState
+from vellum.workflows.workflows.base import BaseWorkflow
+from vellum.workflows.workflows.event_filters import workflow_sandbox_event_filter
+
+
+class NestedInputs(BaseInputs):
+    value: str
+
+
+class NestedNode(BaseNode):
+    value = NestedInputs.value
+
+    class Outputs(BaseOutputs):
+        result: str
+
+    def run(self) -> Outputs:
+        return self.Outputs(result=f"nested: {self.value}")
+
+
+class NestedWorkflow(BaseWorkflow[NestedInputs, BaseState]):
+    graph = NestedNode
+
+    class Outputs(BaseOutputs):
+        result = NestedNode.Outputs.result
+
+
+class ParentInputs(BaseInputs):
+    value: str
+
+
+class SubworkflowNode(InlineSubworkflowNode):
+    subworkflow_inputs = {
+        "value": ParentInputs.value,
+    }
+    subworkflow = NestedWorkflow
+
+
+class ParentWorkflow(BaseWorkflow[ParentInputs, BaseState]):
+    graph = SubworkflowNode
+
+    class Outputs(BaseOutputs):
+        result = SubworkflowNode.Outputs.result
+
+
+def test_workflow_sandbox_event_filter__filters_nested_workflow_snapshotted_events():
+    """
+    Tests that workflow_sandbox_event_filter filters out snapshotted events from nested workflows.
+    """
+
+    workflow = ParentWorkflow()
+
+    # WHEN we stream the workflow with workflow_sandbox_event_filter
+    events = list(
+        workflow.stream(
+            inputs=ParentInputs(value="test"),
+            event_filter=workflow_sandbox_event_filter,
+        )
+    )
+
+    snapshotted_events = [e for e in events if e.name == "workflow.execution.snapshotted"]
+    assert len(snapshotted_events) > 0
+
+    for event in snapshotted_events:
+        assert event.workflow_definition == ParentWorkflow
+
+
+def test_workflow_sandbox_event_filter__includes_root_workflow_snapshotted_events():
+    """
+    Tests that workflow_sandbox_event_filter includes snapshotted events from the root workflow.
+    """
+
+    class SimpleNode(BaseNode):
+        class Outputs(BaseOutputs):
+            result: str = "simple"
+
+        def run(self) -> Outputs:
+            return self.Outputs()
+
+    class SimpleWorkflow(BaseWorkflow[BaseInputs, BaseState]):
+        graph = SimpleNode
+
+        class Outputs(BaseOutputs):
+            result = SimpleNode.Outputs.result
+
+    workflow = SimpleWorkflow()
+
+    # WHEN we stream the workflow with workflow_sandbox_event_filter
+    events = list(
+        workflow.stream(
+            inputs=BaseInputs(),
+            event_filter=workflow_sandbox_event_filter,
+        )
+    )
+
+    snapshotted_events = [e for e in events if e.name == "workflow.execution.snapshotted"]
+    assert len(snapshotted_events) > 0
+
+    for event in snapshotted_events:
+        assert event.workflow_definition == SimpleWorkflow
+
+
+def test_workflow_sandbox_event_filter__includes_nested_workflow_non_snapshotted_events():
+    """
+    Tests that workflow_sandbox_event_filter includes non-snapshotted events from nested workflows.
+    """
+
+    workflow = ParentWorkflow()
+
+    # WHEN we stream the workflow with workflow_sandbox_event_filter
+    events = list(
+        workflow.stream(
+            inputs=ParentInputs(value="test"),
+            event_filter=workflow_sandbox_event_filter,
+        )
+    )
+
+    nested_workflow_events = [
+        e for e in events if hasattr(e, "workflow_definition") and e.workflow_definition == NestedWorkflow
+    ]
+    assert len(nested_workflow_events) > 0
+
+    for event in nested_workflow_events:
+        assert event.name != "workflow.execution.snapshotted"

{vellum_ai-1.8.2.dist-info → vellum_ai-1.8.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vellum-ai
-Version: 1.8.2
+Version: 1.8.4
 Summary: 
 License: MIT
 Requires-Python: >=3.9,<4.0