py-data-engine 0.1.0__py3-none-any.whl

data_engine/__init__.py

@@ -0,0 +1,37 @@
+"""Top-level package for the Data Engine workbook runtime."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from data_engine.authoring.builder import Batch
+    from data_engine.authoring.builder import FileRef
+    from data_engine.authoring.builder import Flow
+    from data_engine.authoring.builder import FlowContext
+    from data_engine.authoring.builder import discover_flows, load_flow, run
+
+__all__ = ["Batch", "FileRef", "Flow", "FlowContext", "discover_flows", "load_flow", "run"]
+
+
+def __getattr__(name: str):
+    """Lazy-load runtime symbols so lightweight helpers can import package submodules safely."""
+    if name in {"Batch", "FileRef", "Flow", "FlowContext", "discover_flows", "load_flow", "run"}:
+        from data_engine.authoring.builder import Batch
+        from data_engine.authoring.builder import FileRef
+        from data_engine.authoring.builder import Flow
+        from data_engine.authoring.builder import FlowContext
+        from data_engine.authoring.builder import discover_flows
+        from data_engine.authoring.builder import load_flow
+        from data_engine.authoring.builder import run
+
+        return {
+            "Batch": Batch,
+            "FileRef": FileRef,
+            "Flow": Flow,
+            "FlowContext": FlowContext,
+            "discover_flows": discover_flows,
+            "load_flow": load_flow,
+            "run": run,
+        }[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

data_engine/application/__init__.py

@@ -0,0 +1,39 @@
+"""Host-agnostic application use cases built on top of services and domain models."""
+
+from data_engine.application.actions import ActionStateApplication
+from data_engine.application.catalog import FlowCatalogApplication, FlowCatalogLoadResult, FlowCatalogPresentation
+from data_engine.application.control import FlowRefreshResult, OperatorActionResult, OperatorControlApplication
+from data_engine.application.details import DetailApplication, SelectedFlowPresentation
+from data_engine.application.runtime import (
+    DaemonCommandResult,
+    EngineRunCompletion,
+    FlowStateRefreshPlan,
+    ManualRunCompletion,
+    RuntimeApplication,
+    RuntimeLogMessage,
+    RuntimeSnapshotPresentation,
+    RuntimeSyncState,
+)
+from data_engine.application.workspace import WorkspaceBinding, WorkspaceSessionApplication
+
+__all__ = [
+    "ActionStateApplication",
+    "DaemonCommandResult",
+    "DetailApplication",
+    "EngineRunCompletion",
+    "FlowStateRefreshPlan",
+    "FlowRefreshResult",
+    "FlowCatalogApplication",
+    "FlowCatalogLoadResult",
+    "FlowCatalogPresentation",
+    "ManualRunCompletion",
+    "OperatorActionResult",
+    "OperatorControlApplication",
+    "RuntimeApplication",
+    "RuntimeLogMessage",
+    "RuntimeSnapshotPresentation",
+    "RuntimeSyncState",
+    "SelectedFlowPresentation",
+    "WorkspaceSessionApplication",
+    "WorkspaceBinding",
+]

data_engine/application/actions.py

@@ -0,0 +1,42 @@
+"""Host-agnostic operator action-state use cases."""
+
+from __future__ import annotations
+
+from data_engine.domain import OperatorActionContext, SelectedFlowState
+
+
+class ActionStateApplication:
+    """Own host-neutral action-context assembly for operator surfaces."""
+
+    def build_action_context(
+        self,
+        *,
+        card,
+        flow_states: dict[str, str],
+        runtime_session,
+        flow_groups_by_name: dict[str, str | None],
+        active_flow_states,
+        has_logs: bool,
+        has_automated_flows: bool,
+        workspace_available: bool = True,
+        selected_run_group_present: bool = False,
+    ) -> OperatorActionContext:
+        """Return one operator action context from current runtime and selection state."""
+        selected_flow = SelectedFlowState.from_runtime(
+            card=card,
+            flow_states=flow_states,
+            runtime_session=runtime_session,
+            flow_groups_by_name=flow_groups_by_name,
+            active_flow_states=active_flow_states,
+            has_logs=has_logs,
+        )
+        return OperatorActionContext(
+            runtime_session=runtime_session,
+            selected_flow=selected_flow,
+            has_automated_flows=has_automated_flows,
+            workspace_available=workspace_available,
+            selected_run_group_present=selected_run_group_present,
+        )
+
+
+__all__ = ["ActionStateApplication"]

data_engine/application/catalog.py

@@ -0,0 +1,151 @@
+"""Host-agnostic flow catalog use cases."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from data_engine.authoring.model import FlowValidationError
+from data_engine.domain import FlowCatalogEntry, FlowCatalogLike, FlowCatalogState
+from data_engine.platform.workspace_models import WorkspacePaths
+from data_engine.services import FlowCatalogService
+from data_engine.views.presentation import group_cards
+
+
+@dataclass(frozen=True)
+class FlowCatalogLoadResult:
+    """Normalized result of one workspace catalog load attempt."""
+
+    catalog_state: FlowCatalogState
+    loaded: bool
+    error_text: str | None = None
+
+
+@dataclass(frozen=True)
+class FlowCatalogPresentation:
+    """Normalized grouped catalog presentation shared by operator surfaces."""
+
+    entries: tuple[FlowCatalogEntry, ...]
+    grouped_entries: tuple[tuple[str, tuple[FlowCatalogEntry, ...]], ...]
+    selected_flow_name: str | None
+
+    @property
+    def entries_by_name(self) -> dict[str, FlowCatalogEntry]:
+        """Return entries keyed by internal flow name."""
+        return {entry.name: entry for entry in self.entries}
+
+    @property
+    def selected_entry(self) -> FlowCatalogEntry | None:
+        """Return the normalized selected entry, if any."""
+        if self.selected_flow_name is None:
+            return None
+        return self.entries_by_name.get(self.selected_flow_name)
+
+    @property
+    def cards(self) -> tuple[FlowCatalogLike, ...]:
+        """Return catalog entries under the shared flow metadata protocol."""
+        return self.entries
+
+    @property
+    def grouped_cards(self) -> tuple[tuple[str, tuple[FlowCatalogLike, ...]], ...]:
+        """Return grouped entries under the shared flow metadata protocol."""
+        return self.grouped_entries
+
+    @property
+    def selected_card(self) -> FlowCatalogLike | None:
+        """Return the selected flow metadata under the shared flow protocol."""
+        return self.selected_entry
+
+    @property
+    def selected_list_index(self) -> int | None:
+        """Return the list index for the selected flow in a grouped header+item list."""
+        if self.selected_flow_name is None:
+            return None
+        index = 0
+        for _group_name, entries in self.grouped_entries:
+            index += 1
+            for entry in entries:
+                if entry.name == self.selected_flow_name:
+                    return index
+                index += 1
+        return None
+
+
+class FlowCatalogApplication:
+    """Own host-neutral flow catalog loading and state transitions."""
+
+    def __init__(self, *, flow_catalog_service: FlowCatalogService) -> None:
+        self.flow_catalog_service = flow_catalog_service
+
+    def load_state(
+        self,
+        *,
+        workspace_root: Path,
+        current_state: FlowCatalogState | None = None,
+    ) -> FlowCatalogState:
+        """Load discovered entries and merge them into one catalog state."""
+        base = current_state or FlowCatalogState.empty()
+        entries = self.flow_catalog_service.load_entries(workspace_root=workspace_root)
+        return base.with_entries(entries).with_empty_message("")
+
+    def empty_state(
+        self,
+        *,
+        message: str = "",
+        current_state: FlowCatalogState | None = None,
+    ) -> FlowCatalogState:
+        """Return an empty catalog state with one host-provided message."""
+        base = current_state or FlowCatalogState.empty()
+        return FlowCatalogState.empty(empty_message=message).with_selected_flow_name(base.selected_flow_name)
+
+    def select_flow(
+        self,
+        *,
+        catalog_state: FlowCatalogState,
+        flow_name: str | None,
+    ) -> FlowCatalogState:
+        """Return catalog state with one normalized selected flow."""
+        return catalog_state.with_selected_flow_name(flow_name)
+
+    def build_presentation(
+        self,
+        *,
+        catalog_state: FlowCatalogState,
+    ) -> FlowCatalogPresentation:
+        """Return grouped UI-friendly catalog presentation from one catalog state."""
+        grouped = tuple(
+            (bucket.group_name, bucket.entries)
+            for bucket in group_cards(catalog_state.entries)
+        )
+        return FlowCatalogPresentation(
+            entries=catalog_state.entries,
+            grouped_entries=grouped,
+            selected_flow_name=catalog_state.selected_flow_name,
+        )
+
+    def load_workspace_catalog(
+        self,
+        *,
+        workspace_paths: WorkspacePaths,
+        current_state: FlowCatalogState | None = None,
+        missing_message: str = "No flow modules discovered.",
+    ) -> FlowCatalogLoadResult:
+        """Return one normalized catalog load result for a resolved workspace binding."""
+        if not workspace_paths.flow_modules_dir.is_dir():
+            return FlowCatalogLoadResult(
+                catalog_state=self.empty_state(message=missing_message, current_state=current_state),
+                loaded=False,
+            )
+        try:
+            catalog_state = self.load_state(
+                workspace_root=workspace_paths.workspace_root,
+                current_state=current_state,
+            )
+        except FlowValidationError as exc:
+            message = str(exc)
+            return FlowCatalogLoadResult(
+                catalog_state=self.empty_state(message=message, current_state=current_state),
+                loaded=False,
+                error_text=message,
+            )
+        return FlowCatalogLoadResult(catalog_state=catalog_state, loaded=True)

data_engine/application/control.py

@@ -0,0 +1,213 @@
+"""Host-agnostic operator control and action use cases."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from data_engine.domain import RuntimeSessionState
+from data_engine.hosts.daemon.manager import WorkspaceDaemonManager
+from data_engine.platform.workspace_models import WorkspacePaths, authored_workspace_is_available
+from data_engine.services import DaemonStateService
+
+from data_engine.application.runtime import RuntimeApplication
+
+
+@dataclass(frozen=True)
+class OperatorActionResult:
+    """Normalized result for one operator control action."""
+
+    requested: bool
+    sync_after: bool = False
+    ensure_daemon_started: bool = False
+    status_text: str | None = None
+    error_text: str | None = None
+
+
+@dataclass(frozen=True)
+class FlowRefreshResult:
+    """Normalized result for one flow-refresh request."""
+
+    reload_catalog: bool
+    sync_after: bool = False
+    status_text: str | None = None
+    warning_text: str | None = None
+    error_text: str | None = None
+
+
+class OperatorControlApplication:
+    """Own host-neutral action orchestration for operator surfaces."""
+
+    def __init__(
+        self,
+        *,
+        runtime_application: RuntimeApplication,
+        daemon_state_service: DaemonStateService,
+    ) -> None:
+        self.runtime_application = runtime_application
+        self.daemon_state_service = daemon_state_service
+
+    def run_selected_flow(
+        self,
+        *,
+        paths: WorkspacePaths,
+        runtime_session: RuntimeSessionState,
+        selected_flow_name: str | None,
+        selected_flow_valid: bool,
+        selected_flow_group: str | None,
+        selected_flow_group_active: bool,
+        blocked_status_text: str,
+        timeout: float = 2.0,
+    ) -> OperatorActionResult:
+        """Validate and request one manual run for the selected flow."""
+        if not authored_workspace_is_available(paths):
+            return OperatorActionResult(requested=False, error_text="Workspace root is no longer available.")
+        if selected_flow_name is None:
+            return OperatorActionResult(requested=False, status_text="Select one flow first.")
+        if not selected_flow_valid:
+            return OperatorActionResult(
+                requested=False,
+                status_text=f"{selected_flow_name} is invalid and cannot run.",
+            )
+        if selected_flow_group_active or runtime_session.runtime_active or runtime_session.manual_run_active:
+            return OperatorActionResult(requested=False)
+        if not runtime_session.control_available:
+            return OperatorActionResult(requested=False, status_text=blocked_status_text)
+        result = self.runtime_application.run_flow(
+            paths,
+            name=selected_flow_name,
+            wait=False,
+            timeout=timeout,
+        )
+        if not result.ok:
+            return OperatorActionResult(
+                requested=False,
+                error_text=_verbose_action_error(
+                    f"run {selected_flow_name}",
+                    result.error,
+                ),
+            )
+        return OperatorActionResult(
+            requested=True,
+            sync_after=True,
+            status_text=f"Running {selected_flow_name}...",
+        )
+
+    def start_engine(
+        self,
+        *,
+        paths: WorkspacePaths,
+        runtime_session: RuntimeSessionState,
+        has_automated_flows: bool,
+        blocked_status_text: str,
+        timeout: float = 2.0,
+    ) -> OperatorActionResult:
+        """Validate and request automated engine start."""
+        if not authored_workspace_is_available(paths):
+            return OperatorActionResult(requested=False, error_text="Workspace root is no longer available.")
+        if runtime_session.runtime_active or runtime_session.runtime_stopping or runtime_session.manual_run_active:
+            return OperatorActionResult(requested=False)
+        if not runtime_session.control_available:
+            return OperatorActionResult(requested=False, status_text=blocked_status_text)
+        if not has_automated_flows:
+            return OperatorActionResult(requested=False, status_text="No automated flows are available.")
+        result = self.runtime_application.start_engine(paths, timeout=timeout)
+        if not result.ok:
+            return OperatorActionResult(
+                requested=False,
+                error_text=_verbose_action_error("start the automated engine", result.error),
+            )
+        return OperatorActionResult(requested=True, sync_after=True, status_text="Starting automated engine...")
+
+    def stop_pipeline(
+        self,
+        *,
+        paths: WorkspacePaths,
+        runtime_session: RuntimeSessionState,
+        selected_flow_group: str | None,
+        blocked_status_text: str,
+        timeout: float = 2.0,
+    ) -> OperatorActionResult:
+        """Validate and request stop for the engine or selected manual flow."""
+        if runtime_session.runtime_active:
+            result = self.runtime_application.stop_engine(paths, timeout=timeout)
+            if not result.ok:
+                return OperatorActionResult(
+                    requested=False,
+                    error_text=_verbose_action_error("stop the engine", result.error),
+                )
+            return OperatorActionResult(requested=True, sync_after=True, status_text="Stopping engine...")
+        if runtime_session.manual_run_active:
+            if not runtime_session.control_available:
+                return OperatorActionResult(requested=False, status_text=blocked_status_text)
+            flow_name = runtime_session.active_manual_runs.get(selected_flow_group)
+            if flow_name is None:
+                return OperatorActionResult(requested=False)
+            result = self.runtime_application.stop_flow(paths, name=flow_name, timeout=timeout)
+            if not result.ok:
+                return OperatorActionResult(
+                    requested=False,
+                    error_text=_verbose_action_error(f"stop {flow_name}", result.error),
+                )
+            return OperatorActionResult(requested=True, sync_after=True, status_text="Stopping selected flow...")
+        return OperatorActionResult(requested=False)
+
+    def request_control(self, daemon_manager: WorkspaceDaemonManager) -> OperatorActionResult:
+        """Request workspace control through the daemon-state manager."""
+        try:
+            message = self.daemon_state_service.request_control(daemon_manager)
+        except Exception as exc:
+            return OperatorActionResult(
+                requested=False,
+                error_text=_verbose_action_error("request workspace control", exc),
+            )
+        return OperatorActionResult(
+            requested=True,
+            sync_after=True,
+            ensure_daemon_started=True,
+            status_text=message,
+        )
+
+    def refresh_flows(
+        self,
+        *,
+        paths: WorkspacePaths,
+        runtime_session: RuntimeSessionState,
+        has_authored_workspace: bool,
+        timeout: float = 5.0,
+    ) -> FlowRefreshResult:
+        """Validate and request one flow refresh while preserving local reload behavior."""
+        if runtime_session.runtime_active or runtime_session.active_manual_runs:
+            return FlowRefreshResult(
+                reload_catalog=False,
+                error_text="Stop active engine or manual runs before refreshing flows.",
+            )
+        if not has_authored_workspace:
+            return FlowRefreshResult(
+                reload_catalog=True,
+                sync_after=True,
+                status_text="No flow modules discovered.",
+            )
+        result = self.runtime_application.refresh_flows(paths, timeout=timeout)
+        if not result.ok:
+            return FlowRefreshResult(
+                reload_catalog=True,
+                sync_after=True,
+                status_text="Reloaded flow definitions.",
+                warning_text=_verbose_action_error("refresh flows", result.error),
+            )
+        return FlowRefreshResult(
+            reload_catalog=True,
+            sync_after=True,
+            status_text="Reloaded flow definitions.",
+        )
+
+
+def _verbose_action_error(action: str, detail: object | None) -> str:
+    """Return a non-terse user-facing failure string for operator control paths."""
+    text = str(detail).strip() if detail is not None else ""
+    if text:
+        return text
+    return f"Failed to {action}. The daemon returned no additional detail."
+
+
+__all__ = ["FlowRefreshResult", "OperatorActionResult", "OperatorControlApplication"]

data_engine/application/details.py

@@ -0,0 +1,73 @@
+"""Host-agnostic selected-flow and run-detail use cases."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from data_engine.domain import FlowCatalogLike, FlowRunState, SelectedFlowDetailState
+
+
+@dataclass(frozen=True)
+class SelectedFlowPresentation:
+    """Normalized selected-flow detail state for operator surfaces."""
+
+    detail_state: SelectedFlowDetailState | None
+    run_groups: tuple[FlowRunState, ...]
+    visible_run_groups: tuple[FlowRunState, ...]
+    selected_run_key: tuple[str, str] | None
+    empty_text: str
+
+    @property
+    def run_group_signature(self) -> tuple[tuple[str, str], ...]:
+        """Return the stable visible run-list signature for diffing/render reuse."""
+        return tuple(group.key for group in self.visible_run_groups)
+
+    @property
+    def selected_run_group(self) -> FlowRunState | None:
+        """Return the normalized selected run group, if any."""
+        if self.selected_run_key is not None:
+            for run_group in self.run_groups:
+                if run_group.key == self.selected_run_key:
+                    return run_group
+        return self.run_groups[0] if self.run_groups else None
+
+
+class DetailApplication:
+    """Own host-neutral selected-flow detail and run selection behavior."""
+
+    def build_selected_flow_presentation(
+        self,
+        *,
+        card: FlowCatalogLike | None,
+        tracker,
+        flow_states: dict[str, str],
+        run_groups: tuple[FlowRunState, ...],
+        selected_run_key: tuple[str, str] | None,
+        max_visible_runs: int | None = None,
+    ) -> SelectedFlowPresentation:
+        """Return the selected-flow detail state and normalized run selection."""
+        if card is None:
+            return SelectedFlowPresentation(
+                detail_state=None,
+                run_groups=(),
+                visible_run_groups=(),
+                selected_run_key=None,
+                empty_text="Select one flow to see details.",
+            )
+        detail_state = SelectedFlowDetailState.from_flow(
+            card,
+            tracker,
+            flow_states=flow_states,
+        )
+        normalized_key = selected_run_key if any(group.key == selected_run_key for group in run_groups) else (run_groups[0].key if run_groups else None)
+        visible_run_groups = run_groups[-max_visible_runs:] if max_visible_runs is not None and max_visible_runs >= 0 else run_groups
+        return SelectedFlowPresentation(
+            detail_state=detail_state,
+            run_groups=run_groups,
+            visible_run_groups=visible_run_groups,
+            selected_run_key=normalized_key,
+            empty_text="",
+        )
+
+
+__all__ = ["DetailApplication", "SelectedFlowPresentation"]