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

data_engine/domain/details.py

@@ -0,0 +1,214 @@
+"""Domain models for selected-flow and run-detail state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from data_engine.domain.catalog import FlowCatalogLike
+
+if TYPE_CHECKING:
+    from data_engine.domain.runs import FlowRunState
+    from data_engine.domain.operations import OperationSessionState
+
+
+@dataclass(frozen=True)
+class FlowSummaryRow:
+    """One labeled row in a flow summary/config display."""
+
+    label: str
+    value: str
+
+    @classmethod
+    def rows_for_flow(
+        cls,
+        card: FlowCatalogLike | None,
+        flow_states: dict[str, str],
+    ) -> tuple["FlowSummaryRow", ...]:
+        """Build summary/config rows for one flow card."""
+        if card is None:
+            return (
+                cls("Flow", "-"),
+                cls("Mode", "-"),
+                cls("Interval", "-"),
+                cls("State", "-"),
+                cls("Source", "-"),
+                cls("Target", "-"),
+            )
+        state = flow_states.get(card.name, card.state)
+        return (
+            cls("Flow", card.name),
+            cls("Mode", card.mode),
+            cls("Interval", card.interval),
+            cls("State", state),
+            cls("Source", card.source_root),
+            cls("Target", card.target_root),
+        )
+
+    @classmethod
+    def pairs_for_flow(
+        cls,
+        card: FlowCatalogLike | None,
+        flow_states: dict[str, str],
+    ) -> tuple[tuple[str, str], ...]:
+        """Build tuple pairs for display surfaces that only need labels and values."""
+        return tuple((row.label, row.value) for row in cls.rows_for_flow(card, flow_states))
+
+
+@dataclass(frozen=True)
+class FlowSummaryState:
+    """Explicit summary state for one selected flow."""
+
+    rows: tuple[FlowSummaryRow, ...]
+
+    @classmethod
+    def from_flow(
+        cls,
+        card: FlowCatalogLike | None,
+        flow_states: dict[str, str],
+    ) -> "FlowSummaryState":
+        """Build one summary-state bundle for a selected flow."""
+        return cls(rows=FlowSummaryRow.rows_for_flow(card, flow_states))
+
+    @property
+    def pairs(self) -> tuple[tuple[str, str], ...]:
+        """Return the legacy label/value pair projection for simple surfaces."""
+        return tuple((row.label, row.value) for row in self.rows)
+
+
+@dataclass(frozen=True)
+class OperationArtifactState:
+    """Artifact/inspection rules for one operation row."""
+
+    operation_name: str
+
+    @property
+    def inspectable(self) -> bool:
+        """Return whether the operation can surface an inspectable artifact."""
+        return bool(self.operation_name)
+
+    @property
+    def artifact_key(self) -> str | None:
+        """Return the runtime metadata key produced by this operation."""
+        return self.operation_name or None
+
+    @classmethod
+    def capture_outputs(
+        cls,
+        card: FlowCatalogLike,
+        existing: dict[str, Path],
+        results: object,
+    ) -> dict[str, Path]:
+        """Return updated output-path mappings extracted from completed flow results."""
+        if not isinstance(results, list):
+            return existing.copy()
+        captured = existing.copy()
+        for context in results:
+            metadata = getattr(context, "metadata", None)
+            if not isinstance(metadata, dict):
+                continue
+            step_outputs = metadata.get("step_outputs")
+            if not isinstance(step_outputs, dict):
+                continue
+            for operation_name in card.operation_items:
+                value = step_outputs.get(cls(operation_name).artifact_key)
+                if isinstance(value, Path):
+                    captured[operation_name] = value
+        return captured
+
+
+@dataclass(frozen=True)
+class OperationDetailRow:
+    """One operation row in selected-flow detail state."""
+
+    name: str
+    status: str
+    elapsed_seconds: float | None
+
+
+@dataclass(frozen=True)
+class SelectedFlowDetailState:
+    """Surface-agnostic detail state for one selected flow."""
+
+    title: str
+    description: str
+    error: str
+    summary_rows: tuple[FlowSummaryRow, ...]
+    operation_rows: tuple[OperationDetailRow, ...]
+
+    @classmethod
+    def from_flow(
+        cls,
+        card: FlowCatalogLike,
+        tracker: "OperationSessionState",
+        *,
+        flow_states: dict[str, str] | None = None,
+    ) -> "SelectedFlowDetailState":
+        """Build the selected-flow detail state for one card."""
+        summary_rows = FlowSummaryRow.rows_for_flow(card, flow_states or {})
+        operation_rows = tuple(
+            OperationDetailRow(
+                name=operation_name,
+                status=(row_state.status if row_state is not None else "idle"),
+                elapsed_seconds=(row_state.elapsed_seconds if row_state is not None else None),
+            )
+            for operation_name in card.operation_items
+            for row_state in (tracker.row_state(card.name, operation_name),)
+        )
+        return cls(
+            title=card.title,
+            description=card.description or "",
+            error=card.error or "",
+            summary_rows=summary_rows,
+            operation_rows=operation_rows,
+        )
+
+
+@dataclass(frozen=True)
+class RunStepDetailRow:
+    """One step row inside a grouped run detail."""
+
+    step_name: str
+    status: str
+    elapsed_seconds: float | None
+
+
+@dataclass(frozen=True)
+class RunDetailState:
+    """Surface-agnostic detail state for one grouped run."""
+
+    display_label: str
+    source_label: str
+    status: str
+    elapsed_seconds: float | None
+    step_rows: tuple[RunStepDetailRow, ...]
+
+    @classmethod
+    def from_run(cls, run_state: "FlowRunState") -> "RunDetailState":
+        """Build the grouped-run detail state used by operator surfaces."""
+        step_rows = tuple(
+            RunStepDetailRow(
+                step_name=step.step_name,
+                status=step.status,
+                elapsed_seconds=step.elapsed_seconds,
+            )
+            for step in run_state.steps
+        )
+        return cls(
+            display_label=run_state.display_label,
+            source_label=run_state.source_label,
+            status=run_state.status,
+            elapsed_seconds=run_state.elapsed_seconds,
+            step_rows=step_rows,
+        )
+
+__all__ = [
+    "FlowSummaryState",
+    "FlowSummaryRow",
+    "OperationArtifactState",
+    "OperationDetailRow",
+    "RunDetailState",
+    "RunStepDetailRow",
+    "SelectedFlowDetailState",
+]

data_engine/domain/diagnostics.py

@@ -0,0 +1,56 @@
+"""Diagnostic state models shared across operator surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DoctorCheck:
+    """One doctor check row with status and message."""
+
+    status: str
+    message: str
+
+
+@dataclass(frozen=True)
+class ProcessInfo:
+    """One relevant local process row."""
+
+    pid: int
+    ppid: int
+    status: str
+    command: str
+
+
+@dataclass(frozen=True)
+class ClassifiedProcessInfo:
+    """One local process row with Data Engine role classification."""
+
+    pid: int
+    ppid: int
+    status: str
+    command: str
+    kind: str
+
+    @property
+    def is_defunct(self) -> bool:
+        """Return whether this process row represents a zombie/defunct process."""
+        return self.status.startswith("Z")
+
+    @property
+    def is_orphaned(self) -> bool:
+        """Return whether this process row is now parented by init/launchd."""
+        return self.ppid == 1
+
+
+@dataclass(frozen=True)
+class WorkspaceLeaseDiagnostic:
+    """One workspace lease health row for CLI diagnostics."""
+
+    workspace_id: str
+    lease_pid: int | None
+    state: str
+    stale: bool
+    local_owner: bool
+

data_engine/domain/errors.py

@@ -0,0 +1,104 @@
+"""Explicit parsed error models shared across operator surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+
+
+@dataclass(frozen=True)
+class StructuredErrorField:
+    """One labeled field in a parsed operator error."""
+
+    label: str
+    value: str
+
+
+@dataclass(frozen=True)
+class StructuredErrorState:
+    """Structured presentation state for one operator-facing error."""
+
+    title: str
+    fields: tuple[StructuredErrorField, ...]
+    detail: str
+    raw_text: str
+
+    @classmethod
+    def parse(cls, text: str) -> "StructuredErrorState | None":
+        """Parse one known verbose error string into structured fields when possible."""
+        step_match = re.fullmatch(
+            r'Flow "(?P<flow>[^"]+)" failed in step "(?P<step>[^"]+)"'
+            r'(?: \(function (?P<function>[^)]+)\))?'
+            r'(?: for source "(?P<source>[^"]+)")?: (?P<detail>.+)',
+            text,
+        )
+        if step_match is not None:
+            fields = [
+                StructuredErrorField("Flow", step_match.group("flow")),
+                StructuredErrorField("Phase", "step"),
+                StructuredErrorField("Step", step_match.group("step")),
+            ]
+            function_name = step_match.group("function")
+            source_name = step_match.group("source")
+            if function_name:
+                fields.append(StructuredErrorField("Function", function_name))
+            if source_name:
+                fields.append(StructuredErrorField("Source", source_name))
+            return cls(
+                title="Flow Failed",
+                fields=tuple(fields),
+                detail=step_match.group("detail"),
+                raw_text=text,
+            )
+
+        build_match = re.fullmatch(
+            r'Flow module "(?P<flow_module>[^"]+)" failed during build\(\)'
+            r'(?: in (?P<function>[^:]+))?: (?P<detail>.+)',
+            text,
+        )
+        if build_match is not None:
+            fields = [
+                StructuredErrorField("Flow Module", build_match.group("flow_module")),
+                StructuredErrorField("Phase", "build"),
+            ]
+            function_name = build_match.group("function")
+            if function_name:
+                fields.append(StructuredErrorField("Function", function_name))
+            return cls(
+                title="Flow Module Failed",
+                fields=tuple(fields),
+                detail=build_match.group("detail"),
+                raw_text=text,
+            )
+
+        import_match = re.fullmatch(r'Flow module "(?P<flow_module>[^"]+)" failed during import: (?P<detail>.+)', text)
+        if import_match is not None:
+            return cls(
+                title="Flow Module Failed",
+                fields=(
+                    StructuredErrorField("Flow Module", import_match.group("flow_module")),
+                    StructuredErrorField("Phase", "import"),
+                ),
+                detail=import_match.group("detail"),
+                raw_text=text,
+            )
+
+        missing_match = re.fullmatch(
+            r"Flow module '(?P<flow_module>[^']+)' is not available in (?P<path>.+?)\. Available flow modules: (?P<available>.+)\.",
+            text,
+        )
+        if missing_match is not None:
+            return cls(
+                title="Flow Module Not Found",
+                fields=(
+                    StructuredErrorField("Flow Module", missing_match.group("flow_module")),
+                    StructuredErrorField("Workspace", missing_match.group("path")),
+                    StructuredErrorField("Available", missing_match.group("available")),
+                ),
+                detail=text,
+                raw_text=text,
+            )
+        return None
+
+
+__all__ = ["StructuredErrorField", "StructuredErrorState"]

data_engine/domain/inspection.py

@@ -0,0 +1,99 @@
+"""Inspection and preview state models shared across operator surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from data_engine.domain.catalog import FlowCatalogLike
+from data_engine.domain.details import FlowSummaryState
+
+
+@dataclass(frozen=True)
+class FlowStepOutputsState:
+    """Latest known inspectable outputs for one flow."""
+
+    outputs: dict[str, Path] = field(default_factory=dict)
+
+    def get(self, operation_name: str) -> Path | None:
+        """Return the last known output path for one operation."""
+        return self.outputs.get(operation_name)
+
+    def has(self, operation_name: str) -> bool:
+        """Return whether one operation currently has an inspectable output."""
+        return operation_name in self.outputs
+
+
+@dataclass(frozen=True)
+class StepOutputIndex:
+    """Latest known inspectable outputs keyed by flow and operation."""
+
+    flow_outputs: dict[str, FlowStepOutputsState] = field(default_factory=dict)
+
+    @classmethod
+    def empty(cls) -> "StepOutputIndex":
+        """Return an empty output index."""
+        return cls()
+
+    @classmethod
+    def from_mapping(cls, mapping: dict[str, dict[str, Path]]) -> "StepOutputIndex":
+        """Build one output index from legacy nested flow/output mappings."""
+        return cls(
+            flow_outputs={
+                flow_name: FlowStepOutputsState(outputs=dict(outputs))
+                for flow_name, outputs in mapping.items()
+            }
+        )
+
+    def outputs_for(self, flow_name: str) -> FlowStepOutputsState:
+        """Return output state for one flow."""
+        return self.flow_outputs.get(flow_name, FlowStepOutputsState())
+
+    def output_path(self, flow_name: str, operation_name: str) -> Path | None:
+        """Return the last known output path for one flow operation."""
+        return self.outputs_for(flow_name).get(operation_name)
+
+    def has_output(self, flow_name: str, operation_name: str) -> bool:
+        """Return whether one flow operation has an inspectable output."""
+        return self.outputs_for(flow_name).has(operation_name)
+
+    def with_flow_outputs(self, flow_name: str, outputs: dict[str, Path]) -> "StepOutputIndex":
+        """Return a copy with one flow's outputs replaced."""
+        next_flow_outputs = dict(self.flow_outputs)
+        next_flow_outputs[flow_name] = FlowStepOutputsState(outputs=dict(outputs))
+        return type(self)(flow_outputs=next_flow_outputs)
+
+
+@dataclass(frozen=True)
+class ConfigPreviewState:
+    """Surface-agnostic state for one flow config/summary preview."""
+
+    title: str
+    description: str
+    summary: FlowSummaryState
+
+    @classmethod
+    def from_flow(
+        cls,
+        card: FlowCatalogLike | None,
+        flow_states: dict[str, str],
+    ) -> "ConfigPreviewState":
+        """Build one config-preview state bundle for a selected flow."""
+        if card is None:
+            return cls(
+                title="No flow selected",
+                description="",
+                summary=FlowSummaryState.from_flow(None, flow_states),
+            )
+        return cls(
+            title=card.title,
+            description=card.description or "No flow description provided.",
+            summary=FlowSummaryState.from_flow(card, flow_states),
+        )
+
+
+__all__ = [
+    "ConfigPreviewState",
+    "FlowStepOutputsState",
+    "StepOutputIndex",
+]

data_engine/domain/logs.py

@@ -0,0 +1,118 @@
+"""Domain models and parsing helpers for runtime log-entry state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+import logging
+from pathlib import Path
+import re
+from typing import Literal
+
+LogKind = Literal["flow", "system"]
+
+
+@dataclass(frozen=True)
+class RuntimeStepEvent:
+    """Parsed runtime event derived from one builder log record."""
+
+    flow_name: str
+    step_name: str | None
+    source_label: str
+    status: str
+    elapsed_seconds: float | None = None
+    run_id: str | None = None
+
+
+@dataclass(frozen=True)
+class FlowLogEntry:
+    """One runtime log entry captured for operator surfaces."""
+
+    line: str
+    kind: LogKind
+    event: RuntimeStepEvent | None = None
+    flow_name: str | None = None
+    created_at_utc: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    @staticmethod
+    def format_runtime_message(message: str) -> str:
+        """Render a runtime message into a compact operator-facing single line."""
+        return format_runtime_message(message)
+
+
+def short_source_label(value: str | None) -> str:
+    """Collapse a source path down to a filename-style label."""
+    if value in (None, "None", ""):
+        return "-"
+    return Path(str(value)).name
+
+
+def format_runtime_message(message: str) -> str:
+    """Render a runtime message into a compact operator-facing single line."""
+    step_match = re.search(r"flow=(?P<flow>\S+) step=(?P<step>.+?) source=(?P<source>.+?) status=(?P<status>\S+)", message)
+    if step_match is not None:
+        source = short_source_label(step_match.group("source"))
+        return f"{step_match.group('flow')}  {step_match.group('step')}  {step_match.group('status')}  {source}"
+
+    flow_match = re.search(r"flow=(?P<flow>\S+) source=(?P<source>.+?) status=(?P<status>\S+)", message)
+    if flow_match is not None:
+        source = short_source_label(flow_match.group("source"))
+        return f"{flow_match.group('flow')}  {flow_match.group('status')}  {source}"
+
+    return re.sub(r"/[^ ]+", lambda match: Path(match.group(0)).name, message)
+
+
+def format_log_line(record: logging.LogRecord) -> str:
+    """Render runtime logs into a compact operator-facing single line."""
+    return format_runtime_message(record.getMessage())
+
+
+def parse_runtime_message(message: str) -> RuntimeStepEvent | None:
+    """Parse one runtime message into structured flow/step event data when possible."""
+    step_match = re.search(
+        r"run=(?P<run>\S+) flow=(?P<flow>\S+) step=(?P<step>.+?) source=(?P<source>.+?) status=(?P<status>\S+)(?: elapsed=(?P<elapsed>\S+))?",
+        message,
+    )
+    if step_match is not None:
+        elapsed = step_match.group("elapsed")
+        return RuntimeStepEvent(
+            run_id=step_match.group("run"),
+            flow_name=step_match.group("flow"),
+            step_name=step_match.group("step"),
+            source_label=short_source_label(step_match.group("source")),
+            status=step_match.group("status"),
+            elapsed_seconds=float(elapsed) if elapsed is not None else None,
+        )
+
+    flow_match = re.search(
+        r"run=(?P<run>\S+) flow=(?P<flow>\S+) source=(?P<source>.+?) status=(?P<status>\S+)(?: elapsed=(?P<elapsed>\S+))?",
+        message,
+    )
+    if flow_match is not None:
+        elapsed = flow_match.group("elapsed")
+        return RuntimeStepEvent(
+            run_id=flow_match.group("run"),
+            flow_name=flow_match.group("flow"),
+            step_name=None,
+            source_label=short_source_label(flow_match.group("source")),
+            status=flow_match.group("status"),
+            elapsed_seconds=float(elapsed) if elapsed is not None else None,
+        )
+    return None
+
+
+def parse_runtime_event(record: logging.LogRecord) -> RuntimeStepEvent | None:
+    """Parse one runtime log record into structured flow/step event data when possible."""
+    return parse_runtime_message(record.getMessage())
+
+
+__all__ = [
+    "FlowLogEntry",
+    "LogKind",
+    "RuntimeStepEvent",
+    "format_log_line",
+    "format_runtime_message",
+    "parse_runtime_event",
+    "parse_runtime_message",
+    "short_source_label",
+]