hexdag 0.5.0.dev1__py3-none-any.whl

hexdag/core/orchestration/events/observers/models.py

@@ -0,0 +1,111 @@
+"""Observer models and data classes.
+
+This module provides typed data structures for observer implementations,
+following the framework's "Pydantic validation everywhere" principle.
+"""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class AlertType(StrEnum):
+    """Types of alerts that can be triggered."""
+
+    SLOW_NODE = "SLOW_NODE"
+    NODE_FAILURE = "NODE_FAILURE"
+    RESOURCE_EXHAUSTED = "RESOURCE_EXHAUSTED"
+    QUALITY_ISSUE = "QUALITY_ISSUE"
+
+
+class AlertSeverity(StrEnum):
+    """Alert severity levels."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass(slots=True)
+class Alert:
+    """Typed alert data structure.
+
+    Replaces untyped dict[str, Any] with proper validation and type safety.
+
+    Attributes
+    ----------
+    type : AlertType
+        Type of alert
+    node : str
+        Node that triggered the alert
+    message : str
+        Human-readable alert message
+    timestamp : float
+        Unix timestamp when alert was triggered
+    severity : AlertSeverity
+        Alert severity level
+    duration_ms : float, optional
+        Duration in milliseconds (for slow node alerts)
+    threshold_ms : float, optional
+        Threshold that was exceeded (for slow node alerts)
+    error : str, optional
+        Error message (for failure alerts)
+    metadata : dict[str, Any]
+        Additional alert metadata
+    """
+
+    type: AlertType
+    node: str
+    message: str
+    timestamp: float
+    severity: AlertSeverity = AlertSeverity.WARNING
+    duration_ms: float | None = None
+    threshold_ms: float | None = None
+    error: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class NodeMetrics:
+    """Consolidated metrics for a single node.
+
+    Uses single dataclass instead of multiple parallel dict structures.
+    Follows the HandlerEntry pattern from README.md.
+
+    Attributes
+    ----------
+    timings : list[float]
+        List of execution times in milliseconds
+    executions : int
+        Total number of executions
+    failures : int
+        Total number of failures
+    """
+
+    timings: list[float] = field(default_factory=list)
+    executions: int = 0
+    failures: int = 0
+
+    @property
+    def average_ms(self) -> float:
+        """Calculate average execution time."""
+        return sum(self.timings) / len(self.timings) if self.timings else 0.0
+
+    @property
+    def min_ms(self) -> float:
+        """Get minimum execution time."""
+        return min(self.timings) if self.timings else 0.0
+
+    @property
+    def max_ms(self) -> float:
+        """Get maximum execution time."""
+        return max(self.timings) if self.timings else 0.0
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate success rate as percentage."""
+        if self.executions == 0:
+            return 0.0
+        successes = self.executions - self.failures
+        return (successes / self.executions) * 100.0

hexdag/core/orchestration/events/taxonomy.py

@@ -0,0 +1,269 @@
+"""Event taxonomy: registry metadata, envelope building, validation."""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from dataclasses import dataclass, fields
+from datetime import UTC, datetime
+from enum import Enum, StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, ValidationError, field_validator
+
+from .events import EVENT_REGISTRY, Event, EventSpec
+
+# Canonical namespace/action definitions
+EVENT_TYPE_RE = re.compile(r"^[a-z]+:[a-z]+$")
+
+APPROVED_ACTIONS: dict[str, set[str]] = {
+    "pipeline": {"started", "completed", "failed"},
+    "dag": {"started", "completed", "failed"},
+    "wave": {"started", "completed"},
+    "node": {"started", "completed", "failed", "skipped"},
+    "policy": {"decision"},
+    "observer": {"timeout", "error"},
+    "registry": {"resolved", "missing"},
+    "tool": {"called", "completed"},
+    "llm": {"prompt", "response"},
+    "port": set(),
+    "memory": set(),
+}
+
+
+class Severity(StrEnum):
+    """Severity levels used in the event envelope."""
+
+    info = "info"
+    warn = "warn"
+    error = "error"
+
+
+@dataclass(slots=True)
+class EventContext:
+    """Execution context supplied when building an envelope."""
+
+    pipeline: str
+    pipeline_run_id: str
+    tenant: str | None = None
+    project: str | None = None
+    environment: str | None = None
+    correlation_id: str | None = None
+
+
+def generate_event_id(preferred: str | None = None) -> str:
+    """Generate a stable string identifier for an event."""
+    if preferred:
+        return str(preferred)
+
+    func = getattr(uuid, "uuid7", None)
+    if func is not None:
+        return str(func())
+    return str(uuid.uuid4())
+
+
+def _now_rfc3339_ms() -> str:
+    """Return current UTC timestamp with millisecond precision."""
+    return datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def _coerce(value: Any) -> Any:
+    """Convert common non-JSON types into serializable representations."""
+    if isinstance(value, Exception):
+        return str(value)
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, (bytes, bytearray)):
+        return value.decode("utf-8", errors="replace")
+    if hasattr(value, "isoformat"):
+        try:
+            return value.isoformat()
+        except Exception:  # pragma: no cover - fallback path
+            return str(value)
+    return value
+
+
+def _ensure_json_serializable(payload: Any) -> None:
+    """Verify payload can be encoded as JSON using stdlib encoder.
+
+    Raises
+    ------
+    TypeError
+        If ``payload`` cannot be JSON-encoded using the standard library ``json`` module.
+    """
+    try:
+        json.dumps(payload)
+    except TypeError as exc:  # pragma: no cover - surfaced as ValueError via caller
+        raise TypeError(f"attrs not JSON-serializable: {exc}") from exc
+
+
+class EventEnvelope(BaseModel):
+    """Pydantic model describing the canonical event envelope."""
+
+    model_config = ConfigDict(extra="forbid", use_enum_values=True)
+
+    event_type: str
+    event_id: str
+    timestamp: str
+    pipeline: str
+    pipeline_run_id: str
+    severity: Severity
+    attrs: dict[str, Any]
+    node: str | None = None
+    wave: int | None = None
+    tenant: str | None = None
+    project: str | None = None
+    environment: str | None = None
+    correlation_id: str | None = None
+
+    @field_validator("event_type")
+    @classmethod
+    def _validate_event_type_field(cls, value: str) -> str:
+        validate_event_type(value)
+        return value
+
+    @field_validator("timestamp")
+    @classmethod
+    def _validate_timestamp_field(cls, value: str) -> str:
+        _validate_timestamp(value)
+        return value
+
+    @field_validator("attrs")
+    @classmethod
+    def _validate_attrs_field(cls, value: dict[str, Any]) -> dict[str, Any]:
+        _ensure_json_serializable(value)
+        return value
+
+
+def _infer_severity(event_type: str) -> Severity:
+    """Derive severity from event action."""
+    _, action = event_type.split(":", 1)
+    if action in {"failed", "error"}:
+        return Severity.error
+    return Severity.info
+
+
+def _resolve_attr_fields(event: Event, spec: EventSpec) -> tuple[str, ...]:
+    if spec.attr_fields is not None:
+        return spec.attr_fields
+    mapped = set(spec.envelope_fields.values())
+    attr_fields: list[str] = []
+    for field in fields(event):
+        if not field.init:
+            continue
+        if field.name in mapped:
+            continue
+        attr_fields.append(field.name)
+    return tuple(attr_fields)
+
+
+def build_envelope(event: Event, context: EventContext) -> dict[str, Any]:
+    """Convert an internal event object into a canonical envelope dict.
+
+    Raises
+    ------
+    KeyError
+        If the event class is not registered in ``EVENT_REGISTRY``.
+    AttributeError
+        If the event instance is missing an attribute required by the
+        registry mapping.
+    ValueError
+        If the generated payload fails envelope validation.
+    """
+    class_name = type(event).__name__
+    try:
+        spec = EVENT_REGISTRY[class_name]
+    except KeyError as exc:
+        raise KeyError(f"unmapped event class: {class_name}") from exc
+
+    payload: dict[str, Any] = {
+        "event_type": spec.event_type,
+        "event_id": generate_event_id(getattr(event, "event_id", None)),
+        "timestamp": _now_rfc3339_ms(),
+        "pipeline": context.pipeline,
+        "pipeline_run_id": context.pipeline_run_id,
+        "severity": _infer_severity(spec.event_type).value,
+        "attrs": {},
+    }
+
+    # Optional context fields when provided
+    for field in ("tenant", "project", "environment", "correlation_id"):
+        value = getattr(context, field)
+        if value:
+            payload[field] = value
+
+    # Populate mapped top-level fields from the event data
+    for target, attr_name in spec.envelope_fields.items():
+        if not hasattr(event, attr_name):
+            raise AttributeError(
+                f"Event '{class_name}' missing attribute '{attr_name}' required for '{target}'"
+            )
+        value = getattr(event, attr_name)
+        payload[target] = _coerce(value)
+
+    # Build attrs from declared event fields
+    for attr_name in _resolve_attr_fields(event, spec):
+        if not hasattr(event, attr_name):
+            continue
+        payload["attrs"][attr_name] = _coerce(getattr(event, attr_name))
+
+    try:
+        envelope_model = EventEnvelope.model_validate(payload)
+    except ValidationError as exc:  # pragma: no cover - handled via ValueError for callers
+        raise ValueError(str(exc)) from exc
+
+    return envelope_model.model_dump(exclude_none=True)
+
+
+def validate_event_type(event_type: str) -> None:
+    """Ensure event_type follows namespace:action pattern and is approved.
+
+    Raises
+    ------
+    ValueError
+        If the provided event type does not match the canonical pattern or
+        is not part of the approved namespace/action sets.
+    """
+    if not EVENT_TYPE_RE.match(event_type):
+        raise ValueError(f"event_type not matching ^[a-z]+:[a-z]+$: {event_type}")
+    namespace, action = event_type.split(":", 1)
+    actions = APPROVED_ACTIONS.get(namespace)
+    if actions is None or (actions and action not in actions):
+        raise ValueError(f"event_type not in approved sets: {event_type}")
+
+
+def _validate_timestamp(ts: str) -> None:
+    try:
+        datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise ValueError("timestamp must be ISO 8601 compatible") from exc
+
+
+REQUIRED_FIELDS = (
+    "event_type",
+    "event_id",
+    "timestamp",
+    "pipeline",
+    "pipeline_run_id",
+    "severity",
+    "attrs",
+)
+
+
+def validate_envelope(envelope: dict[str, Any]) -> None:
+    """Validate a complete event envelope against required fields and rules.
+
+    Raises
+    ------
+    ValueError
+        If mandatory fields are missing or the payload fails schema validation.
+    """
+    for field_name in REQUIRED_FIELDS:
+        if field_name not in envelope:
+            raise ValueError(f"missing field: {field_name}")
+
+    try:
+        EventEnvelope.model_validate(envelope)
+    except ValidationError as exc:
+        raise ValueError(str(exc)) from exc

hexdag/core/orchestration/hook_context.py

@@ -0,0 +1,237 @@
+"""Context objects, protocols, and constants for hook execution."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from hexdag.core.orchestration.models import NodeExecutionContext
+    from hexdag.core.ports.observer_manager import ObserverManagerPort
+
+
+# Constants for pipeline status (replacing string literals)
+class PipelineStatus(StrEnum):
+    """Pipeline execution status enumeration.
+
+    This replaces string literals for pipeline status with a proper type.
+
+    Attributes
+    ----------
+    SUCCESS : str
+        Pipeline completed successfully
+    FAILED : str
+        Pipeline failed with an error
+    CANCELLED : str
+        Pipeline was cancelled (e.g., timeout)
+    """
+
+    SUCCESS = "success"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass(slots=True)
+class PreHookContext:
+    """Context for pre-DAG hook execution.
+
+    Bundles all parameters needed for pre-DAG hooks into a single object,
+    reducing parameter lists and improving maintainability.
+
+    Attributes
+    ----------
+    ports : dict[str, Any]
+        All available ports for the pipeline
+    context : NodeExecutionContext
+        Execution context for this pipeline run
+    observer_manager : ObserverManagerPort | None
+        Optional observer for event emission
+    pipeline_name : str
+        Name of the pipeline being executed
+
+    Examples
+    --------
+    Example usage::
+
+        ctx = PreHookContext(
+            ports={"llm": openai, "database": postgres},
+            context=execution_context,
+            observer_manager=observer,
+            pipeline_name="my_pipeline"
+        )
+        results = await manager.execute_hooks(ctx)
+    """
+
+    ports: dict[str, Any]
+    context: NodeExecutionContext
+    observer_manager: ObserverManagerPort | None
+    pipeline_name: str
+
+
+@dataclass(slots=True)
+class PostHookContext:
+    """Context for post-DAG hook execution.
+
+    Bundles all parameters needed for post-DAG hooks into a single object,
+    reducing parameter lists and improving maintainability.
+
+    Attributes
+    ----------
+    ports : dict[str, Any]
+        All available ports
+    context : NodeExecutionContext
+        Execution context
+    observer_manager : ObserverManagerPort | None
+        Optional observer manager
+    pipeline_name : str
+        Pipeline name
+    pipeline_status : PipelineStatus
+        Final pipeline status (enum)
+    node_results : dict[str, Any]
+        Results from all executed nodes
+    error : Exception | None
+        Exception if pipeline failed
+
+    Examples
+    --------
+    Example usage::
+
+        ctx = PostHookContext(
+            ports=ports,
+            context=execution_context,
+            observer_manager=observer,
+            pipeline_name="my_pipeline",
+            pipeline_status=PipelineStatus.SUCCESS,
+            node_results={"node1": "result1"},
+            error=None
+        )
+        results = await manager.execute_hooks(ctx)
+    """
+
+    ports: dict[str, Any]
+    context: NodeExecutionContext
+    observer_manager: ObserverManagerPort | None
+    pipeline_name: str
+    pipeline_status: PipelineStatus
+    node_results: dict[str, Any]
+    error: Exception | None = None
+
+    @property
+    def status_str(self) -> str:
+        """Get status as string for backward compatibility.
+
+        Returns
+        -------
+        str
+            Status value ("success", "failed", or "cancelled")
+        """
+        return self.pipeline_status.value
+
+
+class PreHookManagerProtocol(Protocol):
+    """Protocol for pre-DAG hook managers.
+
+    This protocol defines the interface that all pre-DAG hook managers must implement,
+    enabling better testing, dependency injection, and extensibility.
+
+    Examples
+    --------
+    >>> class CustomPreHookManager:
+    ...     async def execute_hooks(
+    ...         self,
+    ...         ports: dict[str, Any],
+    ...         context: NodeExecutionContext,
+    ...         observer_manager: ObserverManagerPort | None,
+    ...         pipeline_name: str,
+    ...     ) -> dict[str, Any]:
+    ...         # Custom implementation
+    ...         return {}
+    """
+
+    async def execute_hooks(
+        self,
+        ports: dict[str, Any],
+        context: NodeExecutionContext,
+        observer_manager: ObserverManagerPort | None,
+        pipeline_name: str,
+    ) -> dict[str, Any]:
+        """Execute all pre-DAG hooks.
+
+        Parameters
+        ----------
+        ports : dict[str, Any]
+            All available ports for the pipeline
+        context : NodeExecutionContext
+            Execution context for this pipeline run
+        observer_manager : ObserverManagerPort | None
+            Optional observer for event emission
+        pipeline_name : str
+            Name of the pipeline being executed
+
+        Returns
+        -------
+        dict[str, Any]
+            Results from all hook executions
+        """
+        ...
+
+
+class PostHookManagerProtocol(Protocol):
+    """Protocol for post-DAG hook managers.
+
+    This protocol defines the interface that all post-DAG hook managers must implement,
+    enabling better testing, dependency injection, and extensibility.
+
+    Examples
+    --------
+    >>> class CustomPostHookManager:
+    ...     async def execute_hooks(
+    ...         self,
+    ...         ports: dict[str, Any],
+    ...         context: NodeExecutionContext,
+    ...         observer_manager: ObserverManagerPort | None,
+    ...         pipeline_name: str,
+    ...         pipeline_status: str,
+    ...         node_results: dict[str, Any],
+    ...         error: Exception | None = None,
+    ...     ) -> dict[str, Any]:
+    ...         # Custom implementation
+    ...         return {}
+    """
+
+    async def execute_hooks(
+        self,
+        ports: dict[str, Any],
+        context: NodeExecutionContext,
+        observer_manager: ObserverManagerPort | None,
+        pipeline_name: str,
+        pipeline_status: str,
+        node_results: dict[str, Any],
+        error: Exception | None = None,
+    ) -> dict[str, Any]:
+        """Execute all post-DAG hooks.
+
+        Parameters
+        ----------
+        ports : dict[str, Any]
+            All available ports
+        context : NodeExecutionContext
+            Execution context
+        observer_manager : ObserverManagerPort | None
+            Optional observer manager
+        pipeline_name : str
+            Pipeline name
+        pipeline_status : str
+            Final pipeline status
+        node_results : dict[str, Any]
+            Results from all executed nodes
+        error : Exception | None
+            Exception if pipeline failed
+
+        Returns
+        -------
+        dict[str, Any]
+            Results from all hook executions
+        """
+        ...