API: Events Package

Events are the stable communication contract for pipeline triggers, lifecycle notifications, and component-level domain events.

Event dataclass

Canonical immutable event exchanged across the core.

Every event in the system shares the same contract regardless of whether it originates from a pipeline component, the orchestrator, or lifecycle instrumentation. Specialised modules may expose helper constructors and event type constants, but the event object itself is always this class.

get 

get(key: str, default: Any = None) -> Any

Return a payload value or default when the key is absent.

require 

require(key: str) -> Any

Return the payload value for key or raise KeyError.

This keeps event consumers explicit about which payload entries are mandatory for a given event type.

EventHandler module-attribute 

EventHandler = Callable[[Event], None]

EventBus

Bases: IEventBus

Thread-safe pub/sub event bus implementing IEventBus.

Two publication paths
  • dispatch — synchronous; used by pipeline components and BranchingCoordinator inside execution threads.
  • publish — async wrapper around dispatch; for callers operating in an asyncio context.
Handler isolation

A failing handler is logged and skipped; it never crashes the publisher or prevents remaining handlers from running.

subscribe 

subscribe(event_type: str, handler: EventHandler) -> None

Register a handler for one event type or wildcard events.

unsubscribe 

unsubscribe(event_type: str, handler: EventHandler) -> None

Remove a handler if it is registered for the event type.

dispatch 

dispatch(event: Event) -> None

Dispatch an event synchronously to matching handlers.

Handler failures are logged and ignored so publication remains isolated.

publish async 

publish(event: Event) -> None

Async-compatible wrapper around dispatch().

clear 

clear() -> None

Remove all registered handlers.

has_subscribers 

has_subscribers(event_type: str) -> bool

Return whether a type-specific or wildcard handler is registered.

PipelineTrigger dataclass

Typed representation of a pipeline trigger event payload.

This value is returned by PipelineEvent.parse() after validating the generic event payload.

PipelineEvent

Factory helper for pipeline trigger events.

The unified event contract is Event. This helper only centralises the trigger event type name and construction logic.

create staticmethod 

create(
    pipeline_id: str,
    context: PipelineContext,
    source: str,
    correlation_id: str | None = None,
    execution_metadata: Mapping[str, Any] | None = None,
) -> Event

Create a generic event that requests pipeline execution.

Parameters:

Name Type Description Default
pipeline_id str

Desired run id.

 required
context PipelineContext

Validated context to execute.

 required
source str

Event producer identifier.

 required
correlation_id str | None

Optional correlation id. Defaults to pipeline_id.

 None
execution_metadata Mapping[str, Any] | None

Optional metadata propagated into execution.

 None

parse staticmethod 

parse(event: Event) -> PipelineTrigger

Parse and validate a unified Event as a pipeline trigger.

PipelineLifecycleEvent

Bases: StrEnum

Lifecycle event types emitted by pipeline runners.

create_pipeline_lifecycle_event 

create_pipeline_lifecycle_event(
    event: PipelineLifecycleEvent,
    pipeline_id: str,
    source: str,
    result_count: int | None = None,
    artifact_count: int | None = None,
    error: Exception | None = None,
    attempt: int = 1,
    correlation_id: str | None = None,
) -> Event

Create a lifecycle event using the unified Event contract.

Parameters:

Name Type Description Default
event PipelineLifecycleEvent

Lifecycle event type.

 required
pipeline_id str

Run identifier.

 required
source str

Event producer identifier.

 required
result_count int | None

Optional analyzer result count for successful runs.

 None
artifact_count int | None

Optional artifact count for successful runs.

 None
error Exception | None

Optional execution or submission error.

 None
attempt int

One-based attempt number associated with the event.

 1
correlation_id str | None

Optional correlation id. Defaults to pipeline_id.

 None