vellum-ai 0.14.41__py3-none-any.whl → 1.11.2__py3-none-any.whl

vellum/workflows/events/stream.py

@@ -0,0 +1,28 @@
+from uuid import UUID
+from typing import Generator, Generic, Iterator, TypeVar
+
+EventType = TypeVar("EventType")
+
+
+class WorkflowEventGenerator(Generic[EventType]):
+    """
+    Generic wrapper for event streams that exposes span_id as a top-level property
+    while maintaining iterator compatibility.
+    """
+
+    def __init__(self, event_generator: Generator[EventType, None, None], span_id: UUID):
+        self._event_generator = event_generator
+        self._span_id = span_id
+
+    @property
+    def span_id(self) -> UUID:
+        """The span_id associated with this workflow stream."""
+        return self._span_id
+
+    def __iter__(self) -> Iterator[EventType]:
+        """Return self to make this object iterable."""
+        return self
+
+    def __next__(self) -> EventType:
+        """Get the next event from the underlying generator."""
+        return next(self._event_generator)

vellum/workflows/events/tests/test_basic_workflow.py

@@ -0,0 +1,50 @@
+import logging
+from uuid import uuid4
+
+from vellum.workflows import BaseWorkflow
+from vellum.workflows.context import execution_context
+from vellum.workflows.nodes.bases import BaseNode
+from vellum.workflows.workflows.event_filters import all_workflow_event_filter
+
+
+class StartNode(BaseNode):
+    pass
+
+
+class TrivialWorkflow(BaseWorkflow):
+    graph = StartNode
+
+
+logger = logging.getLogger(__name__)
+
+
+def test_basic_workflow_monitoring_context_flow():
+    """Test that monitoring creates the correct workflow→node context hierarchy using streamed events.
+    What's missing:
+    - span_id from previous event mapping to parent context
+    """
+
+    workflow = TrivialWorkflow()
+
+    with execution_context(trace_id=uuid4()):
+        events = list(workflow.stream(event_filter=all_workflow_event_filter))
+
+    # Verify workflow succeeded
+    assert len(events) >= 2
+    assert events[0].name == "workflow.execution.initiated"
+    assert events[-1].name == "workflow.execution.fulfilled"
+
+    # Collect all events with parent context
+    events_with_parent = [event for event in events if event.parent is not None]
+
+    assert len(events_with_parent) > 0, "Expected at least some events with parent context"
+
+    # Filter for node events
+    node_events = [event for event in events if event.name.startswith("node.")]
+    assert len(node_events) > 0, "Expected at least some node events"
+
+    # Verify each node event has the workflow as its parent context
+    for event in node_events:
+        assert event.parent is not None, "Node event should have parent context"
+        assert event.parent.type == "WORKFLOW", "Node event parent should be workflow"
+        assert event.parent.workflow_definition.name == "TrivialWorkflow", "Parent workflow name mismatch"

vellum/workflows/events/tests/test_event.py

@@ -1,5 +1,5 @@
 import pytest
-from datetime import datetime
+from datetime import datetime, timezone
 from uuid import UUID
 
 from deepdiff import DeepDiff
@@ -7,6 +7,7 @@ from deepdiff import DeepDiff
 from vellum.client.core.pydantic_utilities import UniversalBaseModel
 from vellum.workflows.constants import undefined
 from vellum.workflows.errors.types import WorkflowError, WorkflowErrorCode
+from vellum.workflows.events.exception_handling import stream_initialization_exception
 from vellum.workflows.events.node import (
     NodeExecutionFulfilledBody,
     NodeExecutionFulfilledEvent,
@@ -26,8 +27,10 @@ from vellum.workflows.events.workflow import (
     WorkflowExecutionStreamingBody,
     WorkflowExecutionStreamingEvent,
 )
+from vellum.workflows.exceptions import WorkflowInitializationException
 from vellum.workflows.inputs.base import BaseInputs
 from vellum.workflows.nodes.bases.base import BaseNode
+from vellum.workflows.nodes.displayable.tool_calling_node.utils import ElseNode, RouterNode
 from vellum.workflows.outputs.base import BaseOutput
 from vellum.workflows.references.vellum_secret import VellumSecretReference
 from vellum.workflows.state.base import BaseState
@@ -55,7 +58,7 @@ class MockWorkflow(BaseWorkflow[MockInputs, BaseState]):
 name_parts = __name__.split(".")
 module_root = name_parts[: name_parts.index("events")]
 mock_workflow_uuid = str(uuid4_from_hash(MockWorkflow.__qualname__))
-mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
+mock_node_uuid = str(MockNode.__id__)
 
 
 @pytest.mark.parametrize(
@@ -64,7 +67,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
         (
             WorkflowExecutionInitiatedEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=WorkflowExecutionInitiatedBody(
@@ -75,7 +78,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "workflow.execution.initiated",
@@ -90,14 +93,18 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     },
                     "display_context": None,
                     "initial_state": None,
+                    "workflow_version_exec_config": None,
+                    "server_metadata": None,
+                    "trigger": None,
                 },
                 "parent": None,
+                "links": None,
             },
         ),
         (
             NodeExecutionInitiatedEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=NodeExecutionInitiatedBody(
@@ -119,7 +126,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "node.execution.initiated",
@@ -128,6 +135,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                         "id": mock_node_uuid,
                         "name": "MockNode",
                         "module": module_root + ["events", "tests", "test_event"],
+                        "exclude_from_monitoring": False,
                     },
                     "inputs": {
                         "node_foo": "bar",
@@ -141,6 +149,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                         "id": mock_node_uuid,
                         "name": "MockNode",
                         "module": module_root + ["events", "tests", "test_event"],
+                        "exclude_from_monitoring": False,
                     },
                     "parent": {
                         "workflow_definition": {
@@ -155,12 +164,13 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     "type": "WORKFLOW_NODE",
                     "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 },
+                "links": None,
             },
         ),
         (
             WorkflowExecutionStreamingEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=WorkflowExecutionStreamingBody(
@@ -174,7 +184,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "workflow.execution.streaming",
@@ -190,12 +200,13 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     },
                 },
                 "parent": None,
+                "links": None,
             },
         ),
         (
             WorkflowExecutionFulfilledEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=WorkflowExecutionFulfilledBody(
@@ -208,7 +219,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "workflow.execution.fulfilled",
@@ -221,14 +232,56 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     "outputs": {
                         "example": "foo",
                     },
+                    "final_state": None,
+                    "server_metadata": None,
                 },
                 "parent": None,
+                "links": None,
+            },
+        ),
+        (
+            WorkflowExecutionFulfilledEvent(
+                id=UUID("123e4567-e89b-12d3-a456-426614174000"),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
+                trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
+                span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
+                body=WorkflowExecutionFulfilledBody(
+                    workflow_definition=MockWorkflow,
+                    outputs=MockNode.Outputs(
+                        example="foo",
+                    ),
+                    final_state=BaseState(writable_value=42),
+                ),
+            ),
+            {
+                "id": "123e4567-e89b-12d3-a456-426614174000",
+                "api_version": "2024-10-25",
+                "timestamp": "2024-01-01T12:00:00Z",
+                "trace_id": "123e4567-e89b-12d3-a456-426614174000",
+                "span_id": "123e4567-e89b-12d3-a456-426614174000",
+                "name": "workflow.execution.fulfilled",
+                "body": {
+                    "workflow_definition": {
+                        "id": mock_workflow_uuid,
+                        "name": "MockWorkflow",
+                        "module": module_root + ["events", "tests", "test_event"],
+                    },
+                    "outputs": {
+                        "example": "foo",
+                    },
+                    "final_state": {
+                        "writable_value": 42,
+                    },
+                    "server_metadata": None,
+                },
+                "parent": None,
+                "links": None,
             },
         ),
         (
             WorkflowExecutionRejectedEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=WorkflowExecutionRejectedBody(
@@ -242,7 +295,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "workflow.execution.rejected",
@@ -255,15 +308,19 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     "error": {
                         "message": "Workflow failed",
                         "code": "USER_DEFINED_ERROR",
+                        "raw_data": None,
+                        "stacktrace": None,
                     },
+                    "stacktrace": None,
                 },
                 "parent": None,
+                "links": None,
             },
         ),
         (
             NodeExecutionStreamingEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=NodeExecutionStreamingBody(
@@ -277,7 +334,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "node.execution.streaming",
@@ -286,6 +343,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                         "id": mock_node_uuid,
                         "name": "MockNode",
                         "module": module_root + ["events", "tests", "test_event"],
+                        "exclude_from_monitoring": False,
                     },
                     "output": {
                         "name": "example",
@@ -293,12 +351,13 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     },
                 },
                 "parent": None,
+                "links": None,
             },
         ),
         (
             NodeExecutionFulfilledEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=NodeExecutionFulfilledBody(
@@ -312,7 +371,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "node.execution.fulfilled",
@@ -321,6 +380,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                         "id": mock_node_uuid,
                         "name": "MockNode",
                         "module": module_root + ["events", "tests", "test_event"],
+                        "exclude_from_monitoring": False,
                     },
                     "outputs": {
                         "example": "foo",
@@ -333,12 +393,13 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     "mocked": None,
                 },
                 "parent": None,
+                "links": None,
             },
         ),
         (
             NodeExecutionFulfilledEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=NodeExecutionFulfilledBody(
@@ -352,7 +413,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "node.execution.fulfilled",
@@ -361,6 +422,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                         "id": mock_node_uuid,
                         "name": "MockNode",
                         "module": module_root + ["events", "tests", "test_event"],
+                        "exclude_from_monitoring": False,
                     },
                     "outputs": {},
                     "invoked_ports": [
@@ -371,12 +433,13 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                     "mocked": None,
                 },
                 "parent": None,
+                "links": None,
             },
         ),
         (
             NodeExecutionFulfilledEvent(
                 id=UUID("123e4567-e89b-12d3-a456-426614174000"),
-                timestamp=datetime(2024, 1, 1, 12, 0, 0),
+                timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
                 trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
                 body=NodeExecutionFulfilledBody(
@@ -390,7 +453,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
             {
                 "id": "123e4567-e89b-12d3-a456-426614174000",
                 "api_version": "2024-10-25",
-                "timestamp": "2024-01-01T12:00:00",
+                "timestamp": "2024-01-01T12:00:00Z",
                 "trace_id": "123e4567-e89b-12d3-a456-426614174000",
                 "span_id": "123e4567-e89b-12d3-a456-426614174000",
                 "name": "node.execution.fulfilled",
@@ -399,11 +462,13 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
                         "id": mock_node_uuid,
                         "name": "MockNode",
                         "module": module_root + ["events", "tests", "test_event"],
+                        "exclude_from_monitoring": False,
                     },
                     "outputs": {"example": "foo"},
                     "mocked": True,
                 },
                 "parent": None,
+                "links": None,
             },
         ),
     ],
@@ -412,6 +477,7 @@ mock_node_uuid = str(uuid4_from_hash(MockNode.__qualname__))
         "node.execution.initiated",
         "workflow.execution.streaming",
         "workflow.execution.fulfilled",
+        "workflow.execution.fulfilled_with_state",
         "workflow.execution.rejected",
         "node.execution.streaming",
         "node.execution.fulfilled",
@@ -448,3 +514,62 @@ def test_parent_context__deserialize_from_json__invalid_parent_context():
     assert event.parent.type == "UNKNOWN"
     assert event.parent.span_id == UUID("123e4567-e89b-12d3-a456-426614174000")
     assert event.parent.parent is None
+
+
+def test_workflow_event_generator_stream_initialization_exception():
+    """
+    Tests that stream_initialization_exception yields both initiated and rejected events with proper correlation.
+    """
+    exception = WorkflowInitializationException("Test initialization error", workflow_definition=MockWorkflow)
+
+    events = list(stream_initialization_exception(exception))
+
+    assert len(events) == 2
+
+    initiated_event = events[0]
+    assert initiated_event.name == "workflow.execution.initiated"
+    assert initiated_event.body.inputs is not None
+    assert initiated_event.body.initial_state is None
+    assert initiated_event.body.workflow_definition == MockWorkflow
+
+    rejected_event = events[1]
+    assert rejected_event.name == "workflow.execution.rejected"
+    assert rejected_event.body.error.message == "Test initialization error"
+    assert rejected_event.body.workflow_definition == MockWorkflow
+
+    assert initiated_event.trace_id == rejected_event.trace_id
+    assert initiated_event.span_id == rejected_event.span_id
+
+
+def test_node_execution_initiated_event_includes_exclude_from_monitoring():
+    """Test exclude_from_monitoring is included in node_definition when node has __exclude_from_monitoring__."""
+    router_node_event = NodeExecutionInitiatedEvent(
+        id=UUID("123e4567-e89b-12d3-a456-426614174001"),
+        timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
+        trace_id=UUID("123e4567-e89b-12d3-a456-426614174001"),
+        span_id=UUID("123e4567-e89b-12d3-a456-426614174001"),
+        body=NodeExecutionInitiatedBody(
+            node_definition=RouterNode,
+            inputs={},
+        ),
+    )
+
+    serialized = router_node_event.model_dump(mode="json")
+    assert "exclude_from_monitoring" in serialized["body"]["node_definition"]
+    assert serialized["body"]["node_definition"]["exclude_from_monitoring"] is True
+
+    # Test with ElseNode
+    else_node_event = NodeExecutionInitiatedEvent(
+        id=UUID("123e4567-e89b-12d3-a456-426614174000"),
+        timestamp=datetime(2024, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
+        trace_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
+        span_id=UUID("123e4567-e89b-12d3-a456-426614174000"),
+        body=NodeExecutionInitiatedBody(
+            node_definition=ElseNode,
+            inputs={},
+        ),
+    )
+
+    serialized = else_node_event.model_dump(mode="json")
+    assert "exclude_from_monitoring" in serialized["body"]["node_definition"]
+    assert serialized["body"]["node_definition"]["exclude_from_monitoring"] is True

vellum/workflows/events/types.py

@@ -1,13 +1,13 @@
 from datetime import datetime
 import json
 from uuid import UUID, uuid4
-from typing import Annotated, Any, Literal, Optional, Union, get_args
+from typing import Annotated, Any, List, Literal, Optional, Union, get_args
 
 from pydantic import Field, GetCoreSchemaHandler, Tag, ValidationInfo
 from pydantic_core import CoreSchema, core_schema
 
-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
 from vellum.workflows.types.definition import VellumCodeResourceDefinition
 from vellum.workflows.types.utils import datetime_now
 
@@ -24,7 +24,7 @@ def default_serializer(obj: Any) -> Any:
     return json.loads(
         json.dumps(
             obj,
-            cls=DefaultStateEncoder,
+            cls=VellumJsonEncoder,
         )
     )
 
@@ -74,12 +74,36 @@ class WorkflowSandboxParentContext(BaseParentContext):
 
 class APIRequestParentContext(BaseParentContext):
     type: Literal["API_REQUEST"] = "API_REQUEST"
+    api_actor_id: Optional[str] = None
+    api_actor_type: Optional[str] = None
+    api_actor_label: Optional[str] = None
 
 
 class UnknownParentContext(BaseParentContext):
     type: Literal["UNKNOWN"] = "UNKNOWN"
 
 
+# Setting external parent context for external workflows
+class ExternalParentContext(BaseParentContext):
+    type: Literal["EXTERNAL"] = "EXTERNAL"
+
+
+class ScheduledTriggerContext(BaseParentContext):
+    type: Literal["SCHEDULED"] = "SCHEDULED"
+    trigger_id: UUID
+
+
+class IntegrationTriggerContext(BaseParentContext):
+    type: Literal["INTEGRATION"] = "INTEGRATION"
+    trigger_id: UUID
+
+
+class SpanLink(UniversalBaseModel):
+    trace_id: str
+    type: Literal["TRIGGERED_BY", "PREVIOUS_SPAN", "ROOT_SPAN"]
+    span_context: "ParentContext"
+
+
 def _cast_parent_context_discriminator(v: Any) -> Any:
     if v in PARENT_CONTEXT_TYPES:
         return v
@@ -138,6 +162,9 @@ ParentContext = Annotated[
         PromptDeploymentParentContext,
         WorkflowSandboxParentContext,
         APIRequestParentContext,
+        ExternalParentContext,
+        ScheduledTriggerContext,
+        IntegrationTriggerContext,
         UnknownParentContext,
     ],
     ParentContextDiscriminator(),
@@ -158,3 +185,4 @@ class BaseEvent(UniversalBaseModel):
     trace_id: UUID
     span_id: UUID
     parent: Optional[ParentContext] = None
+    links: Optional[List[SpanLink]] = None