hexastack-flow 0.5.0__py3-none-any.whl

hexastack_flow/__init__.py

@@ -0,0 +1,59 @@
+"""Hexastack Flow - Hexagonal workflow orchestration framework.
+
+Notes/Architectural Intent:
+    Integrates the zero-daemon hexaflow workflow execution engine into Hexastack,
+    providing CQRS command/query steps, saga migration, relational checkpoint persistence,
+    and lifecycle domain event broadcasting.
+"""
+
+from hexaflow import RetryPolicy, StageExecutionMode, Workflow
+
+from hexastack_flow import adapters, domain, infra, ports
+from hexastack_flow.adapters.cqrs.runner import CqrsWorkflowRunner
+from hexastack_flow.adapters.cqrs.steps import (
+    CommandStep,
+    QueryStep,
+    as_command_step,
+    as_query_step,
+)
+from hexastack_flow.adapters.events.publisher import WorkflowEventPublisher
+from hexastack_flow.adapters.storage.sqlalchemy import SqlAlchemyWorkflowStore
+from hexastack_flow.domain.events import (
+    WorkflowAbortedEvent,
+    WorkflowCompletedEvent,
+    WorkflowStartedEvent,
+    WorkflowStepCompletedEvent,
+    WorkflowSuspendedEvent,
+)
+from hexastack_flow.domain.models import (
+    CqrsStepMetadata,
+    WorkflowExecutionResult,
+)
+from hexastack_flow.infra.bootstrap import FlowBootstrapper
+from hexastack_flow.ports.orchestrator import CqrsWorkflowOrchestratorPort
+
+__all__ = [
+    "adapters",
+    "as_command_step",
+    "as_query_step",
+    "CommandStep",
+    "CqrsStepMetadata",
+    "CqrsWorkflowOrchestratorPort",
+    "CqrsWorkflowRunner",
+    "domain",
+    "FlowBootstrapper",
+    "infra",
+    "ports",
+    "QueryStep",
+    "RetryPolicy",
+    "SqlAlchemyWorkflowStore",
+    "StageExecutionMode",
+    "Workflow",
+    "WorkflowAbortedEvent",
+    "WorkflowCompletedEvent",
+    "WorkflowEventPublisher",
+    "WorkflowExecutionResult",
+    "WorkflowStartedEvent",
+    "WorkflowStepCompletedEvent",
+    "WorkflowSuspendedEvent",
+]

hexastack_flow/adapters/__init__.py

@@ -0,0 +1,29 @@
+"""Adapters for hexastack-flow.
+
+Notes/Architectural Intent:
+    Exports CQRS, Storage, and Event adapters bridging hexaflow into Hexastack.
+"""
+
+from hexastack_flow.adapters import cqrs, events, storage
+from hexastack_flow.adapters.cqrs import (
+    CommandStep,
+    CqrsWorkflowRunner,
+    QueryStep,
+    as_command_step,
+    as_query_step,
+)
+from hexastack_flow.adapters.events import WorkflowEventPublisher
+from hexastack_flow.adapters.storage import SqlAlchemyWorkflowStore
+
+__all__ = [
+    "as_command_step",
+    "as_query_step",
+    "CommandStep",
+    "cqrs",
+    "CqrsWorkflowRunner",
+    "events",
+    "QueryStep",
+    "SqlAlchemyWorkflowStore",
+    "storage",
+    "WorkflowEventPublisher",
+]

hexastack_flow/adapters/cqrs/__init__.py

@@ -0,0 +1,21 @@
+"""CQRS adapters for hexaflow workflow execution.
+
+Notes/Architectural Intent:
+    Adapters connecting Hexastack CQRS buses and legacy saga models to hexaflow.
+"""
+
+from hexastack_flow.adapters.cqrs.runner import CqrsWorkflowRunner
+from hexastack_flow.adapters.cqrs.steps import (
+    CommandStep,
+    QueryStep,
+    as_command_step,
+    as_query_step,
+)
+
+__all__ = [
+    "as_command_step",
+    "as_query_step",
+    "CommandStep",
+    "CqrsWorkflowRunner",
+    "QueryStep",
+]

hexastack_flow/adapters/cqrs/runner.py

@@ -0,0 +1,212 @@
+"""CQRS workflow runner adapter implementing CqrsWorkflowOrchestratorPort.
+
+Notes/Architectural Intent:
+    Glues the hexaflow execution engine, state store, and event bus together.
+    Translates hexaflow state objects into Hexastack domain results and
+    publishes lifecycle domain events.
+"""
+
+from datetime import UTC, datetime
+from typing import Any
+
+from hexaflow.adapters.engines.local_async import AsyncioWorkflowEngine
+from hexaflow.adapters.storage.in_memory import InMemoryStateStore
+from hexaflow.domain.models import WorkflowDefinition
+from hexaflow.domain.state import StepStatus, WorkflowExecutionState, WorkflowStatus
+from hexaflow.ports.engine import WorkflowEnginePort
+from hexaflow.ports.storage import WorkflowStateStorePort
+
+from hexastack_cqrs.ports.buses import EventBusPort
+from hexastack_flow.domain.events import (
+    WorkflowAbortedEvent,
+    WorkflowCompletedEvent,
+    WorkflowStartedEvent,
+    WorkflowSuspendedEvent,
+)
+from hexastack_flow.domain.models import WorkflowExecutionResult
+from hexastack_flow.ports.orchestrator import CqrsWorkflowOrchestratorPort
+
+__all__ = [
+    "CqrsWorkflowRunner",
+]
+
+
+class CqrsWorkflowRunner(CqrsWorkflowOrchestratorPort):
+    """Orchestrator runner coordinating workflow execution with CQRS buses.
+
+    Notes/Architectural Intent:
+        Implements CqrsWorkflowOrchestratorPort to provide a complete
+        in-process execution runtime with automatic event publishing.
+    """
+
+    def __init__(
+        self,
+        state_store: WorkflowStateStorePort | None = None,
+        engine: WorkflowEnginePort | None = None,
+        event_bus: EventBusPort | None = None,
+    ) -> None:
+        """Initialize runner with state store, execution engine, and event bus.
+
+        Args:
+            state_store: WorkflowStateStorePort for persistence. Defaults to InMemoryStateStore.
+            engine: WorkflowEnginePort for DAG execution. Defaults to AsyncioWorkflowEngine.
+            event_bus: Optional EventBusPort for publishing workflow domain events.
+        """
+        self._store = state_store or InMemoryStateStore()
+        self._engine = engine or AsyncioWorkflowEngine(state_store=self._store)
+        self._event_bus = event_bus
+
+    def execute(
+        self,
+        workflow: WorkflowDefinition,
+        initial_inputs: dict[str, Any] | None = None,
+    ) -> WorkflowExecutionResult:
+        """Execute workflow definition from the first stage.
+
+        Args:
+            workflow: The WorkflowDefinition to run.
+            initial_inputs: Optional dictionary of root arguments.
+
+        Returns:
+            WorkflowExecutionResult summarizing status, step outputs, and timing.
+        """
+        start_time = datetime.now(UTC)
+        state = self._engine.run(workflow, initial_inputs=initial_inputs)
+
+        if self._event_bus is not None:
+            self._event_bus.publish(
+                WorkflowStartedEvent(
+                    run_id=state.run_id,
+                    workflow_name=state.workflow_name,
+                    started_at=start_time,
+                )
+            )
+
+        self._emit_terminal_events(state)
+        return self._to_result(state)
+
+    def resume(
+        self,
+        run_id: str,
+        workflow: WorkflowDefinition,
+        patch_inputs: dict[str, Any] | None = None,
+    ) -> WorkflowExecutionResult:
+        """Resume a suspended workflow run from its latest checkpoints.
+
+        Args:
+            run_id: Unique identifier of the suspended run.
+            workflow: WorkflowDefinition specification matching the run.
+            patch_inputs: Optional updated inputs for the suspended step.
+
+        Returns:
+            WorkflowExecutionResult reflecting post-resumption status.
+        """
+        state = self._engine.resume(run_id, workflow, patch_inputs=patch_inputs)
+        self._emit_terminal_events(state)
+        return self._to_result(state)
+
+    def abort(
+        self,
+        run_id: str,
+        workflow: WorkflowDefinition,
+        reason: str = "Operator aborted",
+    ) -> WorkflowExecutionResult:
+        """Abort a workflow and unwind completed steps via compensation hooks.
+
+        Args:
+            run_id: Unique identifier of the workflow run.
+            workflow: WorkflowDefinition specification containing compensation hooks.
+            reason: Operator rationale or explanation for cancellation.
+
+        Returns:
+            WorkflowExecutionResult reflecting the aborted state.
+        """
+        state = self._engine.abort(run_id, workflow)
+
+        if self._event_bus is not None:
+            self._event_bus.publish(
+                WorkflowAbortedEvent(
+                    run_id=state.run_id,
+                    workflow_name=state.workflow_name,
+                    reason=reason,
+                    aborted_at=datetime.now(UTC),
+                )
+            )
+
+        return self._to_result(state)
+
+    def _emit_terminal_events(self, state: WorkflowExecutionState) -> None:
+        """Publish lifecycle events based on execution state outcome.
+
+        Args:
+            state: WorkflowExecutionState to inspect.
+        """
+        if self._event_bus is None:
+            return
+
+        if state.status == WorkflowStatus.COMPLETED:
+            self._event_bus.publish(
+                WorkflowCompletedEvent(
+                    run_id=state.run_id,
+                    workflow_name=state.workflow_name,
+                    completed_at=state.finished_at or datetime.now(UTC),
+                    total_steps=len(state.step_checkpoints),
+                )
+            )
+        elif state.status == WorkflowStatus.SUSPENDED:
+            failed_step = next(
+                (
+                    name
+                    for name, chk in state.step_checkpoints.items()
+                    if chk.status == StepStatus.FAILED
+                ),
+                "unknown",
+            )
+            self._event_bus.publish(
+                WorkflowSuspendedEvent(
+                    run_id=state.run_id,
+                    stage_name=state.current_stage or "unknown",
+                    step_name=failed_step,
+                    error_type="StepExecutionError",
+                    error_message=state.error_summary
+                    or "Step failed and exhausted retries.",
+                )
+            )
+
+    @staticmethod
+    def _to_result(state: WorkflowExecutionState) -> WorkflowExecutionResult:
+        """Map a hexaflow WorkflowExecutionState into a WorkflowExecutionResult.
+
+        Args:
+            state: Engine execution state.
+
+        Returns:
+            Pydantic WorkflowExecutionResult value object.
+        """
+        completed = tuple(
+            name
+            for name, chk in state.step_checkpoints.items()
+            if chk.status == StepStatus.COMPLETED
+        )
+        failed = tuple(
+            name
+            for name, chk in state.step_checkpoints.items()
+            if chk.status == StepStatus.FAILED
+        )
+        outputs = {
+            name: chk.output_payload
+            for name, chk in state.step_checkpoints.items()
+            if chk.output_payload is not None
+        }
+
+        return WorkflowExecutionResult(
+            run_id=state.run_id,
+            workflow_name=state.workflow_name,
+            status=state.status.value,
+            completed_steps=completed,
+            failed_steps=failed,
+            outputs=outputs,
+            started_at=state.started_at,
+            ended_at=state.finished_at or datetime.now(UTC),
+            error_summary=state.error_summary,
+        )

hexastack_flow/adapters/cqrs/steps.py

@@ -0,0 +1,200 @@
+"""CQRS Command and Query adapters for hexaflow steps.
+
+Notes/Architectural Intent:
+    Bridges hexaflow StepDefinition callables directly to Hexastack CommandBusPort
+    and QueryBusPort. Enables declarative execution of typed domain commands
+    within workflow DAGs, automatically inheriting the full CQRS middleware chain.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from hexaflow.domain.models import StepDefinition
+from hexaflow.domain.state import StepContext
+
+from hexastack_core.domain import Command, Query
+from hexastack_cqrs.ports.buses import CommandBusPort, QueryBusPort
+from hexastack_flow.domain.models import CqrsStepMetadata
+
+__all__ = [
+    "as_command_step",
+    "as_query_step",
+    "CommandStep",
+    "QueryStep",
+]
+
+
+class CommandStep:
+    """Step action adapter dispatching a domain Command via CommandBusPort.
+
+    Notes/Architectural Intent:
+        Callable step action that takes StepContext, extracts inputs to construct
+        a typed Command instance, and dispatches it through the CommandBus.
+    """
+
+    def __init__(
+        self,
+        command_factory: Callable[[StepContext], Command],
+        command_bus: CommandBusPort,
+    ) -> None:
+        """Initialize CommandStep with command factory and bus.
+
+        Args:
+            command_factory: Callable receiving StepContext and producing a Command.
+            command_bus: CommandBusPort implementation for dispatching.
+        """
+        self._factory = command_factory
+        self._bus = command_bus
+
+    def __call__(self, ctx: StepContext) -> Any:
+        """Execute step by creating and dispatching the domain Command.
+
+        Args:
+            ctx: Runtime StepContext provided by hexaflow engine.
+
+        Returns:
+            The result returned by the registered command handler.
+
+        Raises:
+            Exception: Propagates handler execution or validation errors.
+        """
+        command = self._factory(ctx)
+        return self._bus.dispatch(command)
+
+
+class QueryStep:
+    """Step action adapter dispatching a domain Query via QueryBusPort.
+
+    Notes/Architectural Intent:
+        Callable step action that takes StepContext, constructs a typed Query,
+        and retrieves data via QueryBus, making query results available to downstream steps.
+    """
+
+    def __init__(
+        self,
+        query_factory: Callable[[StepContext], Query[Any]],
+        query_bus: QueryBusPort,
+    ) -> None:
+        """Initialize QueryStep with query factory and bus.
+
+        Args:
+            query_factory: Callable receiving StepContext and producing a Query.
+            query_bus: QueryBusPort implementation for dispatching.
+        """
+        self._factory = query_factory
+        self._bus = query_bus
+
+    def __call__(self, ctx: StepContext) -> Any:
+        """Execute step by creating and dispatching the domain Query.
+
+        Args:
+            ctx: Runtime StepContext provided by hexaflow engine.
+
+        Returns:
+            The query result returned by the registered query handler.
+
+        Raises:
+            Exception: Propagates query handler execution errors.
+        """
+        query = self._factory(ctx)
+        return self._bus.dispatch(query)
+
+
+def as_command_step(
+    name: str,
+    command_factory: Callable[[StepContext], Command],
+    command_bus: CommandBusPort,
+    depends_on: tuple[str, ...] = (),
+    compensation_factory: Callable[[StepContext], Command] | None = None,
+    description: str = "",
+    timeout_seconds: float | None = None,
+) -> StepDefinition:
+    """Construct a hexaflow StepDefinition backed by a CommandStep.
+
+    Args:
+        name: Unique step identifier name.
+        command_factory: Callable producing the domain Command from StepContext.
+        command_bus: CommandBusPort to dispatch through.
+        depends_on: Prerequisites for join barrier synchronization.
+        compensation_factory: Optional compensating command factory for rollbacks.
+        description: Architectural description of the step.
+        timeout_seconds: Maximum allowed execution seconds.
+
+    Returns:
+        Configured hexaflow StepDefinition with attached CqrsStepMetadata.
+
+    Raises:
+        ValueError: If name is empty.
+    """
+    if not name:
+        raise ValueError("Step name must not be empty.")
+
+    action = CommandStep(command_factory, command_bus)
+    compensation = (
+        CommandStep(compensation_factory, command_bus)
+        if compensation_factory is not None
+        else None
+    )
+
+    metadata = {
+        "cqrs": CqrsStepMetadata(
+            step_type="command",
+            message_type=name,
+            description=description,
+        ).model_dump(),
+    }
+
+    return StepDefinition(
+        name=name,
+        action=action,
+        compensation=compensation,
+        depends_on=depends_on,
+        timeout_seconds=timeout_seconds,
+        metadata=metadata,
+    )
+
+
+def as_query_step(
+    name: str,
+    query_factory: Callable[[StepContext], Query[Any]],
+    query_bus: QueryBusPort,
+    depends_on: tuple[str, ...] = (),
+    description: str = "",
+    timeout_seconds: float | None = None,
+) -> StepDefinition:
+    """Construct a hexaflow StepDefinition backed by a QueryStep.
+
+    Args:
+        name: Unique step identifier name.
+        query_factory: Callable producing the domain Query from StepContext.
+        query_bus: QueryBusPort to dispatch through.
+        depends_on: Prerequisites for join barrier synchronization.
+        description: Architectural description of the step.
+        timeout_seconds: Maximum allowed execution seconds.
+
+    Returns:
+        Configured hexaflow StepDefinition with attached CqrsStepMetadata.
+
+    Raises:
+        ValueError: If name is empty.
+    """
+    if not name:
+        raise ValueError("Step name must not be empty.")
+
+    action = QueryStep(query_factory, query_bus)
+    metadata = {
+        "cqrs": CqrsStepMetadata(
+            step_type="query",
+            message_type=name,
+            description=description,
+            requires_transaction=False,
+        ).model_dump(),
+    }
+
+    return StepDefinition(
+        name=name,
+        action=action,
+        depends_on=depends_on,
+        timeout_seconds=timeout_seconds,
+        metadata=metadata,
+    )

hexastack_flow/adapters/events/__init__.py

@@ -0,0 +1,11 @@
+"""Event adapters for hexastack-flow.
+
+Notes/Architectural Intent:
+    Adapters publishing workflow lifecycle events over Hexastack event buses.
+"""
+
+from hexastack_flow.adapters.events.publisher import WorkflowEventPublisher
+
+__all__ = [
+    "WorkflowEventPublisher",
+]

hexastack_flow/adapters/events/publisher.py

@@ -0,0 +1,151 @@
+"""Event publishing adapter broadcasting workflow state transitions.
+
+Notes/Architectural Intent:
+    Connects workflow engine state transitions to Hexastack event buses,
+    allowing distributed subscribers or local event handlers to react to
+    workflow progress, suspension, or completion.
+"""
+
+from datetime import UTC, datetime
+from typing import Any
+
+from hexastack_cqrs.ports.buses import EventBusPort
+from hexastack_flow.domain.events import (
+    WorkflowAbortedEvent,
+    WorkflowCompletedEvent,
+    WorkflowStartedEvent,
+    WorkflowStepCompletedEvent,
+    WorkflowSuspendedEvent,
+)
+
+__all__ = [
+    "WorkflowEventPublisher",
+]
+
+
+class WorkflowEventPublisher:
+    """Publisher broadcasting workflow domain events to an EventBusPort.
+
+    Notes/Architectural Intent:
+        Encapsulates construction and dispatching of domain events across
+        in-process or distributed event buses.
+    """
+
+    def __init__(self, event_bus: EventBusPort) -> None:
+        """Initialize publisher with an event bus.
+
+        Args:
+            event_bus: The EventBusPort to publish events through.
+        """
+        self._bus = event_bus
+
+    def publish_started(self, run_id: str, workflow_name: str) -> None:
+        """Broadcast WorkflowStartedEvent.
+
+        Args:
+            run_id: Workflow execution run identifier.
+            workflow_name: Name of the workflow definition.
+        """
+        event = WorkflowStartedEvent(
+            run_id=run_id,
+            workflow_name=workflow_name,
+            started_at=datetime.now(UTC),
+        )
+        self._bus.publish(event)
+
+    def publish_step_completed(
+        self,
+        run_id: str,
+        stage_name: str,
+        step_name: str,
+        attempt_number: int,
+        duration_seconds: float,
+        output_summary: dict[str, Any] | None = None,
+    ) -> None:
+        """Broadcast WorkflowStepCompletedEvent.
+
+        Args:
+            run_id: Workflow execution run identifier.
+            stage_name: Enclosing stage name.
+            step_name: Name of the completed step.
+            attempt_number: Attempt count.
+            duration_seconds: Step execution time in seconds.
+            output_summary: Optional dictionary summarizing key output values.
+        """
+        event = WorkflowStepCompletedEvent(
+            run_id=run_id,
+            stage_name=stage_name,
+            step_name=step_name,
+            attempt_number=attempt_number,
+            duration_seconds=duration_seconds,
+            output_summary=output_summary or {},
+        )
+        self._bus.publish(event)
+
+    def publish_suspended(
+        self,
+        run_id: str,
+        stage_name: str,
+        step_name: str,
+        error_type: str,
+        error_message: str,
+    ) -> None:
+        """Broadcast WorkflowSuspendedEvent.
+
+        Args:
+            run_id: Workflow execution run identifier.
+            stage_name: Stage where suspension occurred.
+            step_name: Step that failed permanently.
+            error_type: Exception class name.
+            error_message: Human-readable error description.
+        """
+        event = WorkflowSuspendedEvent(
+            run_id=run_id,
+            stage_name=stage_name,
+            step_name=step_name,
+            error_type=error_type,
+            error_message=error_message,
+        )
+        self._bus.publish(event)
+
+    def publish_completed(
+        self,
+        run_id: str,
+        workflow_name: str,
+        total_steps: int,
+    ) -> None:
+        """Broadcast WorkflowCompletedEvent.
+
+        Args:
+            run_id: Workflow execution run identifier.
+            workflow_name: Name of the completed workflow.
+            total_steps: Total count of steps evaluated.
+        """
+        event = WorkflowCompletedEvent(
+            run_id=run_id,
+            workflow_name=workflow_name,
+            completed_at=datetime.now(UTC),
+            total_steps=total_steps,
+        )
+        self._bus.publish(event)
+
+    def publish_aborted(
+        self,
+        run_id: str,
+        workflow_name: str,
+        reason: str,
+    ) -> None:
+        """Broadcast WorkflowAbortedEvent.
+
+        Args:
+            run_id: Workflow execution run identifier.
+            workflow_name: Name of the aborted workflow.
+            reason: Cancellation reason description.
+        """
+        event = WorkflowAbortedEvent(
+            run_id=run_id,
+            workflow_name=workflow_name,
+            reason=reason,
+            aborted_at=datetime.now(UTC),
+        )
+        self._bus.publish(event)

hexastack_flow/adapters/storage/__init__.py

@@ -0,0 +1,12 @@
+"""Storage adapters for hexastack-flow state persistence.
+
+Notes/Architectural Intent:
+    Provides relational database persistence for hexaflow workflow states
+    and step checkpoints.
+"""
+
+from hexastack_flow.adapters.storage.sqlalchemy import SqlAlchemyWorkflowStore
+
+__all__ = [
+    "SqlAlchemyWorkflowStore",
+]