contextweave 0.2.0__py3-none-any.whl

context_aware_translation/adapters/qt/task_engine.py

@@ -0,0 +1,392 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QObject, Qt, QTimer, Signal, Slot
+
+from context_aware_translation.workflow.tasks.claims import ResourceClaim
+from context_aware_translation.workflow.tasks.engine_core import EngineCore
+from context_aware_translation.workflow.tasks.exceptions import CancelDispatchRaceError, RunValidationError
+from context_aware_translation.workflow.tasks.models import TaskAction
+
+if TYPE_CHECKING:
+    from context_aware_translation.storage.repositories.task_store import TaskRecord, TaskStore
+    from context_aware_translation.workflow.tasks.handlers.base import TaskTypeHandler
+    from context_aware_translation.workflow.tasks.models import Decision
+    from context_aware_translation.workflow.tasks.worker_deps import WorkerDeps
+
+logger = logging.getLogger(__name__)
+
+
+class TaskEngine(QObject):
+    """QObject orchestrator that drives the task lifecycle."""
+
+    tasks_changed = Signal(str)  # book_id
+    error_occurred = Signal(str)  # message
+    running_work_changed = Signal(bool)  # is_running
+    enqueue_task_changed = Signal(str)  # internal — connected via QueuedConnection to _emit_task_changed
+
+    def __init__(self, *, store: TaskStore, deps: WorkerDeps, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._core = EngineCore(store=store, deps=deps)
+        self._store = store
+        self._autorun_timer: QTimer | None = None
+        self._was_running: bool = self._core.has_running_work()
+
+        # Coalesce rapid-fire task-changed signals into at most one UI
+        # refresh per 250 ms window.  Worker threads emit
+        # ``enqueue_task_changed`` on every DB persist; without
+        # coalescing, 8 connected widgets each re-query the DB on every
+        # emission, starving the event loop.
+        self._pending_book_ids: set[str] = set()
+        self._coalesce_timer = QTimer(self)
+        self._coalesce_timer.setSingleShot(True)
+        self._coalesce_timer.setInterval(250)
+        self._coalesce_timer.timeout.connect(self._flush_task_changed)
+
+        self.enqueue_task_changed.connect(self._emit_task_changed, Qt.ConnectionType.QueuedConnection)
+
+    @property
+    def store(self) -> TaskStore:
+        return self._store
+
+    # ------------------------------------------------------------------
+    # Delegate to core
+    # ------------------------------------------------------------------
+
+    def register_handler(self, handler: TaskTypeHandler) -> None:
+        self._core.register_handler(handler)
+
+    def get_tasks(
+        self,
+        book_id: str,
+        task_type: str | None = None,
+        limit: int | None = None,
+        *,
+        full: bool = False,
+    ) -> list[TaskRecord]:
+        if full:
+            return self._core.get_tasks(book_id, task_type, limit)
+        return self._core.get_tasks_lightweight(book_id, task_type, limit)
+
+    def get_task(self, task_id: str) -> TaskRecord | None:
+        return self._core.get_task(task_id)
+
+    def has_active_worker(self, task_id: str) -> bool:
+        return self._core.has_active_worker(task_id)
+
+    def has_running_work(self) -> bool:
+        return self._core.has_running_work()
+
+    def has_active_claims(self, book_id: str, wanted: frozenset[ResourceClaim]) -> bool:
+        return self._core.has_active_claims(book_id, wanted)
+
+    def preflight(self, task_type: str, book_id: str, params: dict, action: TaskAction) -> Decision:
+        return self._core.preflight(task_type, book_id, params, action)
+
+    def preflight_task(self, task_id: str, action: TaskAction) -> Decision:
+        return self._core.preflight_task(task_id, action)
+
+    def recover_interrupted_tasks(self) -> list[str]:
+        """Normalize stale active-task rows left behind by a previous shutdown."""
+
+        book_ids = sorted(self._core.recover_interrupted_tasks())
+        for book_id in book_ids:
+            self.enqueue_task_changed.emit(book_id)
+        self._emit_running_work_changed_if_needed()
+        return book_ids
+
+    # ------------------------------------------------------------------
+    # Mutation APIs
+    # ------------------------------------------------------------------
+
+    def enqueue_followup_task(self, task_type: str, book_id: str, **params: object) -> None:
+        """Submit a follow-up task (queued only, no immediate start).
+
+        Used by workers to chain tasks (e.g., translation -> reembedding).
+        Failures are logged and re-raised so caller workers can surface
+        partial-success state (e.g. completed_with_errors).
+        """
+        try:
+            record = self._core.submit(task_type, book_id, **params)
+            logger.info("Follow-up %s task %s enqueued for book %s", task_type, record.task_id, book_id)
+            self.enqueue_task_changed.emit(book_id)
+        except Exception:
+            logger.warning("Failed to enqueue follow-up %s for book %s", task_type, book_id, exc_info=True)
+            raise
+
+    def submit(self, task_type: str, book_id: str, **params) -> TaskRecord:
+        """Create a new task row then best-effort start it."""
+        record = self._core.submit(task_type, book_id, **params)
+        try:
+            self._start_action(record.task_id, TaskAction.RUN)
+        except Exception:
+            logger.debug("Best-effort start failed for task %s; will retry on next tick", record.task_id)
+        self._emit_running_work_changed_if_needed()
+        return record
+
+    def submit_and_start(self, task_type: str, book_id: str, **params) -> TaskRecord:
+        """Create a new task row and immediately start it (strict mode).
+
+        Unlike ``submit``, this method guarantees the task either starts
+        successfully or is immediately marked failed.  It never leaves the
+        task in ``queued`` state and never silently discards a created row.
+
+        Raises ``ValueError`` if ``_core.submit`` itself rejects the task
+        (e.g. validate_submit fails).
+        """
+        record = self._core.submit(task_type, book_id, **params)
+        try:
+            self._start_action(record.task_id, TaskAction.RUN)
+        except Exception as exc:
+            reason = f"strict-start failed: {type(exc).__name__}: {exc}"
+            logger.warning("submit_and_start: marking task %s failed — %s", record.task_id, reason)
+            try:
+                self._store.update(record.task_id, status="failed", last_error=reason)
+            except Exception:
+                logger.exception("submit_and_start: could not mark task %s failed", record.task_id)
+            self.enqueue_task_changed.emit(book_id)
+            self._emit_running_work_changed_if_needed()
+            # Re-fetch the record so the caller sees the failed status.
+            updated = self._core.get_task(record.task_id)
+            return updated if updated is not None else record
+        self._emit_running_work_changed_if_needed()
+        return record
+
+    def run_task(self, task_id: str) -> TaskRecord:
+        """Run a task: atomically resets to queued if terminal, then starts it (strict).
+
+        Raises ``ValueError`` if the task cannot be requeued (e.g. config snapshot
+        capture fails or the handler denies the RUN action).
+
+        If the worker fails to start, the task is immediately marked failed so it
+        is never left stranded in ``queued`` state.
+        """
+        record = self._core.ensure_runnable(task_id)  # may raise ValueError
+        try:
+            self._start_action(task_id, TaskAction.RUN)
+        except Exception as exc:
+            reason = f"strict-start failed: {type(exc).__name__}: {exc}"
+            logger.warning("run_task: marking task %s failed — %s", task_id, reason)
+            try:
+                self._store.update(task_id, status="failed", last_error=reason)
+            except Exception:
+                logger.exception("run_task: could not mark task %s failed", task_id)
+            self.enqueue_task_changed.emit(record.book_id)
+            self._emit_running_work_changed_if_needed()
+            updated = self._core.get_task(task_id)
+            return updated if updated is not None else record
+        self._emit_running_work_changed_if_needed()
+        return record
+
+    def rerun(self, task_id: str) -> TaskRecord:
+        """Reset a terminal task to queued then start it (strict).
+
+        Raises ``ValueError`` if the task cannot be rerun (e.g. config snapshot
+        capture fails or the handler denies the RUN action).
+
+        If the worker fails to start, the task is immediately marked failed so it
+        is never left stranded in ``queued`` state.
+        """
+        record = self._core.rerun(task_id)  # may raise ValueError
+        try:
+            self._start_action(task_id, TaskAction.RUN)
+        except Exception as exc:
+            reason = f"strict-start failed: {type(exc).__name__}: {exc}"
+            logger.warning("rerun: marking task %s failed — %s", task_id, reason)
+            try:
+                self._store.update(task_id, status="failed", last_error=reason)
+            except Exception:
+                logger.exception("rerun: could not mark task %s failed", task_id)
+            self.enqueue_task_changed.emit(record.book_id)
+            self._emit_running_work_changed_if_needed()
+            updated = self._core.get_task(task_id)
+            return updated if updated is not None else record
+        self._emit_running_work_changed_if_needed()
+        return record
+
+    def cancel(self, task_id: str) -> None:
+        """Request cancellation only if handler policy allows it."""
+        try:
+            worker = self._core.cancel(task_id)
+            if worker is not None and hasattr(worker, "requestInterruption"):
+                worker.requestInterruption()  # type: ignore[attr-defined]
+            elif worker is None:
+                # No active RUN worker — dispatch explicit cancel action worker
+                # Only if core.cancel() actually accepted the request (cancel_requested=True).
+                record_after = self._core.get_task(task_id)
+                if record_after is not None and record_after.cancel_requested:
+                    try:
+                        self._start_action(task_id, TaskAction.CANCEL)
+                    except (CancelDispatchRaceError, KeyError) as exc:
+                        logger.debug("Cancel action worker not started for task %s", task_id)
+                        self._core.handle_cancel_dispatch_failure(
+                            task_id,
+                            reason=f"cancel dispatch failed: {type(exc).__name__}: {exc}",
+                        )
+            record = self._core.get_task(task_id)
+            if record is not None:
+                self.enqueue_task_changed.emit(record.book_id)
+        finally:
+            self._emit_running_work_changed_if_needed()
+
+    def delete(self, task_id: str) -> None:
+        """Delete a task if handler policy allows it and worker is not active."""
+        try:
+            book_id = self._core.delete(task_id)
+            if book_id is not None:
+                self.enqueue_task_changed.emit(book_id)
+        finally:
+            self._emit_running_work_changed_if_needed()
+
+    def cancel_running_tasks(self, book_id: str) -> None:
+        """Interrupt active workers for the given book and mark them cancel_requested."""
+        workers = self._core.cancel_running_tasks(book_id)
+        for worker in workers:
+            if hasattr(worker, "requestInterruption"):
+                worker.requestInterruption()  # type: ignore[attr-defined]
+        self._emit_running_work_changed_if_needed()
+
+    # ------------------------------------------------------------------
+    # Autorun timer
+    # ------------------------------------------------------------------
+
+    def start_autorun(self, interval_ms: int = 3000) -> None:
+        if self._autorun_timer is None:
+            self._autorun_timer = QTimer(self)
+            self._autorun_timer.timeout.connect(self.tick)
+        self._autorun_timer.start(interval_ms)
+        self._emit_running_work_changed_if_needed()
+
+    def stop_autorun(self) -> None:
+        if self._autorun_timer is not None:
+            self._autorun_timer.stop()
+
+    # ------------------------------------------------------------------
+    # Tick / scan
+    # ------------------------------------------------------------------
+
+    @Slot()
+    def tick(self) -> None:
+        self._core.cleanup_finished_workers()
+        self._emit_running_work_changed_if_needed()
+        try:
+            startable = self._core.scan_autorunnable()
+        except RuntimeError as exc:
+            self.stop_autorun()
+            self.error_occurred.emit(f"Fatal TaskEngine error: {exc}")
+            raise
+        for task_id in startable:
+            try:
+                self._start_action(task_id, TaskAction.RUN)
+            except RunValidationError as exc:
+                # validate_run rejected — mark task failed so it does not loop.
+                logger.warning("Run validation failed for task %s: %s", task_id, exc)
+                try:
+                    self._store.update(task_id, status="failed", last_error=str(exc))
+                except Exception:
+                    logger.exception("Could not mark task %s failed after RunValidationError", task_id)
+                record = self._core.get_task(task_id)
+                if record is not None:
+                    self.enqueue_task_changed.emit(record.book_id)
+                continue
+            except RuntimeError as exc:
+                # Denied action or conflicts should not crash scheduler loop.
+                logger.debug("Skipped task %s in tick: %s", task_id, exc)
+                continue
+            except Exception as exc:  # noqa: BLE001
+                logger.exception("Unexpected autorun error for task %s: %s", task_id, exc)
+                record = self._core.get_task(task_id)
+                if record is not None:
+                    self._core._set_backoff(record.book_id, time.monotonic())
+
+    # ------------------------------------------------------------------
+    # Internal: start a worker
+    # ------------------------------------------------------------------
+
+    def _start_action(self, task_id: str, action: TaskAction) -> None:
+        """Authorize, build worker, connect signals, start."""
+        record, worker, claims = self._core.authorize_start(task_id, action)
+        self._core.register_active_worker(task_id, worker, claims)
+
+        try:
+            # Connect finished signal
+            if hasattr(worker, "finished"):
+                worker.finished.connect(
+                    lambda tid=task_id: self._on_worker_finished(tid),
+                    Qt.ConnectionType.QueuedConnection,
+                )
+
+            worker.start()  # type: ignore[attr-defined]
+        except Exception:
+            self._core.release_task_resources(task_id)
+            self._emit_running_work_changed_if_needed()
+            raise
+
+        self._emit_running_work_changed_if_needed()
+        self.enqueue_task_changed.emit(record.book_id)
+
+    # ------------------------------------------------------------------
+    # Worker lifecycle callbacks
+    # ------------------------------------------------------------------
+
+    def _on_worker_finished(self, task_id: str) -> None:
+        self._core.release_task_resources(task_id)
+        self._emit_running_work_changed_if_needed()
+        record = self._core.get_task(task_id)
+        if record is not None:
+            self.enqueue_task_changed.emit(record.book_id)
+
+    def _emit_running_work_changed_if_needed(self) -> None:
+        is_running = self._core.has_running_work()
+        if is_running != self._was_running:
+            self._was_running = is_running
+            self.running_work_changed.emit(is_running)
+
+    # ------------------------------------------------------------------
+    # Signal relay
+    # ------------------------------------------------------------------
+
+    @Slot(str)
+    def _emit_task_changed(self, book_id: str) -> None:
+        self._pending_book_ids.add(book_id)
+        if not self._coalesce_timer.isActive():
+            self._coalesce_timer.start()
+
+    @Slot()
+    def _flush_task_changed(self) -> None:
+        book_ids = list(self._pending_book_ids)
+        self._pending_book_ids.clear()
+        for book_id in book_ids:
+            self.tasks_changed.emit(book_id)
+
+    # ------------------------------------------------------------------
+    # Shutdown
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        self.stop_autorun()
+        # Flush any coalesced task-changed notifications before tearing down.
+        if self._coalesce_timer.isActive():
+            self._coalesce_timer.stop()
+            self._flush_task_changed()
+        # Request interruption for all active workers
+        for _task_id, worker in self._core.active_worker_items():
+            if hasattr(worker, "requestInterruption"):
+                worker.requestInterruption()  # type: ignore[attr-defined]
+        # Wait up to 5000ms for workers to finish
+        deadline = time.monotonic() + 5.0
+        for _task_id, worker in self._core.active_worker_items():
+            if hasattr(worker, "wait"):
+                remaining_ms = max(0, int((deadline - time.monotonic()) * 1000))
+                worker.wait(remaining_ms)  # type: ignore[attr-defined]
+        # Release claims for any workers that finished
+        self._core.cleanup_finished_workers()
+        self._emit_running_work_changed_if_needed()
+        # Only close the store if no workers are still running
+        if not self._core.has_running_work():
+            self._core.close()
+        else:
+            logger.warning("Skipping store close: %d workers still active", len(self._core.active_worker_items()))

context_aware_translation/adapters/qt/workers/__init__.py

@@ -0,0 +1 @@
+"""Qt worker implementations used by task handlers and import/export flows."""

context_aware_translation/adapters/qt/workers/base_worker.py

@@ -0,0 +1,61 @@
+"""Base worker class for background operations."""
+
+import logging
+
+from PySide6.QtCore import QThread, Signal
+
+from context_aware_translation.core.cancellation import OperationCancelledError
+from context_aware_translation.core.progress import ProgressUpdate
+from context_aware_translation.ui import sleep_inhibitor
+
+logger = logging.getLogger(__name__)
+
+
+class BaseWorker(QThread):
+    """Base worker with common signals and error handling template."""
+
+    progress = Signal(int, int, str)  # current, total, message
+    finished_success = Signal(object)  # result data
+    cancelled = Signal()  # cancelled by user
+    error = Signal(str)  # error message
+
+    def _emit_progress(self, update: ProgressUpdate) -> None:
+        """Convert ProgressUpdate to signal emission."""
+        self._raise_if_cancelled()
+        self.progress.emit(update.current, update.total, update.message)
+        self._raise_if_cancelled()
+
+    def _raise_if_cancelled(self) -> None:
+        """Raise cooperative cancellation if interruption was requested."""
+        if self.isInterruptionRequested():
+            raise OperationCancelledError("Worker interrupted")
+
+    def _is_cancelled(self) -> bool:
+        """Return True when interruption has been requested."""
+        return self.isInterruptionRequested()
+
+    def run(self) -> None:
+        """Execute worker with standard error handling.
+
+        Subclasses should override _execute() instead of run().
+        """
+        sleep_inhibitor.SleepInhibitor.acquire()
+        try:
+            self._raise_if_cancelled()
+            self._execute()
+        except OperationCancelledError:
+            logger.info("%s cancelled", self.__class__.__name__)
+            self.cancelled.emit()
+        except Exception as e:
+            logger.exception(f"{self.__class__.__name__} failed")
+            self.error.emit(f"{type(e).__name__}: {e}")
+        finally:
+            sleep_inhibitor.SleepInhibitor.release()
+
+    def _execute(self) -> None:
+        """Execute the worker's main task.
+
+        Subclasses must override this method to implement their logic.
+        Should emit finished_success signal when complete.
+        """
+        raise NotImplementedError("Subclasses must implement _execute()")

context_aware_translation/adapters/qt/workers/batch_task_overlap_guard.py

@@ -0,0 +1,57 @@
+"""DB-backed overlap guard for batch task reservations."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from context_aware_translation.storage.repositories.task_store import TaskStore
+
+logger = logging.getLogger(__name__)
+
+
+def has_any_batch_task_overlap(
+    task_store: TaskStore,
+    book_id: str,
+    document_ids: list[int] | None,
+    *,
+    exclude_task_ids: set[str] | None = None,
+) -> bool:
+    """Return True when any existing batch task overlaps selected docs.
+
+    Rules:
+    - Overlap semantics match DocumentOperationTracker (None = all docs overlaps everything).
+    - exclude_task_ids: skip these task IDs (e.g. the task being run itself).
+    - No status filtering: all task rows are considered blockers.
+    """
+    tasks = task_store.list_tasks(book_id=book_id, task_type="batch_translation")
+    for task in tasks:
+        if exclude_task_ids and task.task_id in exclude_task_ids:
+            continue
+        task_doc_ids = _parse_task_document_ids(task)
+        if _ids_overlap(task_doc_ids, document_ids):
+            return True
+    return False
+
+
+def _parse_task_document_ids(task: object) -> list[int] | None:
+    """Extract document_ids from a batch task record."""
+    raw = getattr(task, "document_ids_json", None)
+    if raw is None or raw == "" or raw == "null":
+        return None
+    try:
+        parsed = json.loads(raw)
+        if parsed is None:
+            return None
+        return [int(doc_id) for doc_id in parsed]
+    except (json.JSONDecodeError, TypeError, ValueError):
+        return None
+
+
+def _ids_overlap(a: list[int] | None, b: list[int] | None) -> bool:
+    """Check if two document ID sets overlap. None means 'all docs'."""
+    if a is None or b is None:
+        return True
+    return bool(set(a) & set(b))