software/src/orchestration/models.py

1"""Job state models for fault-tolerant Bible translation orchestration.23Provides dataclasses for tracking translation jobs at various granularities:4- VerseJob: Individual verse translation tracking5- BookJob: Book-level progress and status6- BibleJob: Full Bible translation job with configuration snapshot7"""89from __future__ import annotations1011import uuid12from dataclasses import dataclass, field13from datetime import datetime14from enum import Enum15from typing import Any161718class JobStatus(str, Enum):19    """Status of a job at any level (verse, book, or bible)."""2021    PENDING = "pending"22    IN_PROGRESS = "in_progress"23    COMPLETED = "completed"24    FAILED = "failed"25    CANCELLED = "cancelled"262728@dataclass29class VerseJob:30    """Tracks the translation status of a single verse.3132    Attributes:33        book: Book name (e.g., 'john', 'genesis').34        chapter: Chapter number.35        verse: Verse number.36        status: Current job status.37        attempts: Number of translation attempts.38        last_error: Error message from most recent failed attempt.39        worker_pid: PID of worker process currently handling this verse.40        started_at: When translation started.41        completed_at: When translation completed (or failed).42    """4344    book: str45    chapter: int46    verse: int47    status: JobStatus = JobStatus.PENDING48    attempts: int = 049    last_error: str | None = None50    worker_pid: int | None = None51    started_at: datetime | None = None52    completed_at: datetime | None = None5354    @property55    def reference_str(self) -> str:56        """Return verse reference as string (e.g., 'john:1:1')."""57        return f"{self.book}:{self.chapter}:{self.verse}"585960@dataclass61class BookJob:62    """Tracks the translation status of an entire book.6364    Attributes:65        book: Book name (e.g., 'john', 'genesis').66        status: Current job status.67        total_verses: Total number of verses in the book.68        completed_verses: Number of successfully translated verses.69        failed_verses: Number of verses that failed translation.70        worker_pid: PID of worker process handling this book.71        started_at: When book translation started.72        completed_at: When book translation completed.73        error_message: Error message if book failed.74    """7576    book: str77    status: JobStatus = JobStatus.PENDING78    total_verses: int = 079    completed_verses: int = 080    failed_verses: int = 081    worker_pid: int | None = None82    started_at: datetime | None = None83    completed_at: datetime | None = None84    error_message: str | None = None8586    @property87    def pending_verses(self) -> int:88        """Return number of pending verses."""89        return self.total_verses - self.completed_verses - self.failed_verses9091    @property92    def progress_percentage(self) -> float:93        """Return progress as a percentage."""94        if self.total_verses == 0:95            return 0.096        return (self.completed_verses / self.total_verses) * 100979899@dataclass100class BibleJob:101    """Tracks a full Bible translation job.102103    Attributes:104        job_id: Unique identifier for the job (UUID).105        books: List of books to translate.106        status: Current job status.107        config_snapshot: Frozen configuration at job creation.108        created_at: When job was created.109        started_at: When translation started.110        completed_at: When translation completed.111        total_verses: Total verses across all books.112        completed_verses: Total completed verses across all books.113        failed_verses: Total failed verses across all books.114    """115116    job_id: str = field(default_factory=lambda: str(uuid.uuid4()))117    books: list[str] = field(default_factory=list)118    status: JobStatus = JobStatus.PENDING119    config_snapshot: dict[str, Any] = field(default_factory=dict)120    created_at: datetime = field(default_factory=datetime.utcnow)121    started_at: datetime | None = None122    completed_at: datetime | None = None123    total_verses: int = 0124    completed_verses: int = 0125    failed_verses: int = 0126127    @property128    def pending_verses(self) -> int:129        """Return number of pending verses across all books."""130        return self.total_verses - self.completed_verses - self.failed_verses131132    @property133    def progress_percentage(self) -> float:134        """Return overall progress as a percentage."""135        if self.total_verses == 0:136            return 0.0137        return (self.completed_verses / self.total_verses) * 100138139140@dataclass141class BookResult:142    """Result of translating a single book.143144    Attributes:145        book: Book name.146        success: Whether translation succeeded.147        verses_translated: Number of verses successfully translated.148        verses_failed: Number of verses that failed.149        duration_seconds: Total time taken in seconds.150        error_message: Error message if failed.151    """152153    book: str154    success: bool155    verses_translated: int156    verses_failed: int157    duration_seconds: float158    error_message: str | None = None159160161@dataclass162class JobResult:163    """Result of a full Bible translation job.164165    Attributes:166        job_id: Job identifier.167        success: Whether job completed successfully (all books translated).168        books_completed: Number of books fully translated.169        books_failed: Number of books that failed.170        total_verses_translated: Total verses across all books.171        total_verses_failed: Total failed verses across all books.172        duration_seconds: Total time taken in seconds.173        book_results: Individual results for each book.174    """175176    job_id: str177    success: bool178    books_completed: int179    books_failed: int180    total_verses_translated: int181    total_verses_failed: int182    duration_seconds: float183    book_results: list[BookResult] = field(default_factory=list)184185186# All 66 books of the Bible in canonical order187OLD_TESTAMENT_BOOKS = [188    "genesis", "exodus", "leviticus", "numbers", "deuteronomy",189    "joshua", "judges", "ruth", "1samuel", "2samuel",190    "1kings", "2kings", "1chronicles", "2chronicles", "ezra",191    "nehemiah", "esther", "job", "psalms", "proverbs",192    "ecclesiastes", "song_of_solomon", "isaiah", "jeremiah", "lamentations",193    "ezekiel", "daniel", "hosea", "joel", "amos",194    "obadiah", "jonah", "micah", "nahum", "habakkuk",195    "zephaniah", "haggai", "zechariah", "malachi",196]197198NEW_TESTAMENT_BOOKS = [199    "matthew", "mark", "luke", "john", "acts",200    "romans", "1corinthians", "2corinthians", "galatians", "ephesians",201    "philippians", "colossians", "1thessalonians", "2thessalonians", "1timothy",202    "2timothy", "titus", "philemon", "hebrews", "james",203    "1peter", "2peter", "1john", "2john", "3john",204    "jude", "revelation",205]206207ALL_BOOKS = OLD_TESTAMENT_BOOKS + NEW_TESTAMENT_BOOKS208