src/lib/processing/models.py

"""Typed models for the processing log."""

from __future__ import annotations

from dataclasses import dataclass


@dataclass(frozen=True)
class StageRun:
    """One row of processing_log: one (book, stage) attempt."""
    id: int
    book_id: str
    stage: str
    started_at: str
    finished_at: str | None
    success: int | None        # 1 / 0 / None=in-flight
    pages_done: int | None
    engine: str | None         # model id, e.g. 'BAAI/bge-m3'
    provider: str | None       # 'google' | 'deepinfra' | 'local' | ...
    backend: str | None        # where it ran: 'FlagEmbedding-cuda', 'pymupdf', ...
    error: str | None
    duration_ms: int | None

    @property
    def outcome(self) -> str:
        if self.success == 1:
            return "success"
        if self.success == 0:
            return "failed"
        return "in-flight"

    @property
    def where(self) -> str:
        """One-line 'where did this run?' string for table display.

        Combines engine + provider + backend so the user can tell at a glance
        that 'bge-m3' was local FlagEmbedding on CUDA, not a DeepInfra call.
        """
        parts: list[str] = []
        if self.engine:
            parts.append(self.engine)
        suffix = " / ".join(p for p in (self.provider, self.backend) if p)
        if suffix:
            parts.append(f"({suffix})")
        return " ".join(parts) if parts else "—"