echoact 0.1.0__py3-none-any.whl

echoact/__init__.py

@@ -0,0 +1,3 @@
+"""EchoAct — local Korean/English speech generation."""
+
+__version__ = "0.1.0"

echoact/__main__.py

@@ -0,0 +1,117 @@
+"""Launching EchoAct.
+
+F-85 allows one instance per user account, so the very first thing is to
+ask whether one is already running -- before Qt is initialised, before the
+database is opened, and above all before a second worker or a second REST
+listener could exist.
+
+F-79 then decides the shape of the rest: the service is started after the
+window, and a failure to start it is a notice on that window rather than a
+reason not to have one.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from .errors import EchoActError
+from .instance import AlreadyRunning, acquire
+from .util.logging import configure, get_logger
+
+log = get_logger("main")
+
+
+def _fatal(message: str, lock) -> None:
+    """Report and let go of the single-instance lock.
+
+    Releasing matters: a failed start that keeps the lock makes the next
+    attempt look like F-85's "another instance is running", and the user
+    would then be told the opposite of what happened.
+    """
+    try:
+        from PySide6.QtWidgets import QMessageBox
+
+        QMessageBox.critical(None, "EchoAct", message)
+    finally:
+        lock.release()
+
+
+def main(argv: list[str] | None = None) -> int:
+    configure()
+    argv = list(sys.argv if argv is None else argv)
+
+    try:
+        lock = acquire()
+    except AlreadyRunning:
+        # F-85: surface the window that exists.  Nothing is started here,
+        # and the exit is a success -- the user asked to see EchoAct and
+        # EchoAct is now in front of them.
+        log.info("another instance is running; asked it to show itself")
+        return 0
+
+    from PySide6.QtCore import Qt
+    from PySide6.QtWidgets import QApplication
+
+    from .app import Application
+    from .ui import theme
+    from .ui.main_window import MainWindow
+
+    QApplication.setAttribute(Qt.ApplicationAttribute.AA_DontCreateNativeWidgetSiblings, True)
+    qt = QApplication(argv)
+    qt.setApplicationName("EchoAct")
+    qt.setOrganizationName("EchoAct")
+
+    # Before anything measures a glyph: a face registered later would not
+    # be the one the first layout used, and N-13's stability is about the
+    # layout not changing under the reader.
+    from .ui import fonts
+
+    report = fonts.load()
+    if not report.metrics_are_portable:
+        log.info("no bundled typeface; layout measurements are machine-specific")
+
+    try:
+        app = Application()
+    except EchoActError as exc:
+        # Logged before it is shown. A dialog is seen once by whoever is
+        # at the machine; F-25 wants a failure reported, and F-72's
+        # diagnostic export can only carry what reached the log.
+        log.error("startup failed: %s: %s", exc.code.value, exc.message)
+        _fatal(exc.message, lock)
+        return 1
+    except Exception as exc:  # noqa: BLE001 - the last thing between us and silence
+        # Anything that is not an EchoActError is a defect rather than a
+        # condition, and until now it left the process holding a dialog
+        # with nothing in the log to say why.
+        log.exception("startup failed unexpectedly")
+        _fatal(f"EchoAct could not start ({type(exc).__name__}).", lock)
+        return 1
+
+    window = MainWindow(app, theme.Mode.SYSTEM)
+
+    def raise_window() -> None:
+        """Called from the instance listener's thread.
+
+        ``QMetaObject.invokeMethod`` with a queued connection is the only
+        safe way to touch a widget from there.
+        """
+        from PySide6.QtCore import QMetaObject
+
+        QMetaObject.invokeMethod(window, "show", Qt.ConnectionType.QueuedConnection)
+        QMetaObject.invokeMethod(window, "raise_", Qt.ConnectionType.QueuedConnection)
+        QMetaObject.invokeMethod(window, "activateWindow", Qt.ConnectionType.QueuedConnection)
+
+    lock._on_activate = raise_window  # noqa: SLF001 - set once, before any use
+
+    window.show()
+    app.start_service()
+    window._refresh_service_label()  # noqa: SLF001 - the window is ours
+
+    try:
+        return qt.exec()
+    finally:
+        lock.release()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

echoact/app.py

@@ -0,0 +1,315 @@
+"""Composition root: builds the parts and wires them together once.
+
+Everything that has a lifetime is created here, in an order that follows
+from the requirements rather than from convenience:
+
+* Storage first, because F-45's reconciliation has to run before anything
+  can create a new job, and N-02's cleanup of what a forced termination
+  left behind has to run before anything writes into the scratch tree.
+* The engine next, because the GUI, the REST service, and MCP all route
+  through the one generation slot F-47 allows.
+* The local service last, and separately, because F-79 requires the GUI,
+  generation, playback, and the library to stay fully usable when the port
+  cannot be bound -- so a service that fails to start is a notice, never
+  an exception that reaches this far.
+
+No Qt import appears in this module.  The service and the engine must run
+in a headless test, and a GUI import here would make that impossible.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .audio.player import Player
+from .config.settings import Settings, SettingsModelPreferences, SettingsStore
+from .db.backup import BackupScheduler
+from .db.store import Store
+from .domain import Capability
+from .engine.supervisor import WorkerSupervisor
+from .errors import Code, EchoActError, Problem
+from .jobs.engine import JobEngine, clear_temp_tree, expire_one_off_results
+from .models.catalog import MANIFEST
+from .models.registry import ModelRegistry
+from .paths import audio_dir, db_path, ensure_tree, temp_dir
+from .security.credentials import CredentialStore, IssuedCredential
+from .security.ratelimit import RateLimiter
+from .util import ids
+from .util.logging import configure, get_logger, prune_old_logs
+
+log = get_logger("app")
+
+
+@dataclass(slots=True)
+class Startup:
+    """What happened on the way up, for the first screen to report.
+
+    F-25 wants failures reported rather than swallowed, and F-45 wants an
+    interrupted job shown as interrupted.  Both are collected here instead
+    of being logged and forgotten.
+    """
+
+    problems: list[Problem] = field(default_factory=list)
+    interrupted_jobs: tuple[str, ...] = ()
+    missing_results: tuple[str, ...] = ()
+    temp_entries_removed: int = 0
+    expired_results_removed: int = 0
+    owner_credential: IssuedCredential | None = None
+
+    @property
+    def needs_attention(self) -> bool:
+        return bool(self.problems or self.interrupted_jobs or self.missing_results)
+
+
+class Application:
+    """The parts, and their lifetime."""
+
+    def __init__(
+        self,
+        *,
+        data_root: Path | None = None,
+        settings_store: SettingsStore | None = None,
+        supervisor: WorkerSupervisor | None = None,
+    ) -> None:
+        configure()
+        ensure_tree()
+        prune_old_logs(ids.now())
+
+        self.startup = Startup()
+        self.settings_store = settings_store or SettingsStore()
+        self.settings: Settings = self.settings_store.load()
+        self.startup.problems.extend(self.settings_store.problems)
+
+        self.store = Store(
+            db_path() if data_root is None else data_root / "echoact.sqlite3",
+            audio_root=audio_dir() if data_root is None else data_root / "audio",
+            retention_limit_bytes=self.settings.retention_bytes,
+        )
+        # The owner's two model decisions -- accepted licence and
+        # authorised download -- live in the settings file rather than in a
+        # second file of the registry's own.  Two homes would mean the F-80
+        # policy screen and the registry each reporting a licence the other
+        # had never seen.
+        self.registry = ModelRegistry(
+            MANIFEST, preferences=SettingsModelPreferences(self.settings_store)
+        )
+        self.credentials = CredentialStore.load()
+        self.limiter = RateLimiter()
+        self.supervisor = supervisor or WorkerSupervisor()
+        self.engine = JobEngine(
+            store=self.store,
+            supervisor=self.supervisor,
+            registry=self.registry,
+            manifest=MANIFEST,
+            settings=self.settings,
+        )
+        self.player = Player()
+        self.scheduler = BackupScheduler()
+        self.service: Any = None  # set by start_service, if it starts
+
+        self._recover()
+        self._ensure_owner_credential()
+
+    # ------------------------------------------------------------------
+    # Start-up housekeeping
+    # ------------------------------------------------------------------
+
+    def _recover(self) -> None:
+        """F-45 and N-02, in that order.
+
+        Reconciliation first: it reads job rows that may still name files
+        in the scratch tree, so clearing the tree before reconciling would
+        turn "interrupted" into "result missing" for the same job.
+        """
+        try:
+            report = self.store.reconcile_on_start()
+            self.startup.interrupted_jobs = tuple(report.interrupted_job_ids)
+            self.startup.missing_results = tuple(report.missing_result_ids) + tuple(
+                report.corrupt_result_ids
+            )
+        except EchoActError as exc:
+            self.startup.problems.append(Problem(exc.code, exc.message))
+
+        try:
+            self.startup.expired_results_removed = expire_one_off_results(self.store, temp_dir())
+        except EchoActError as exc:
+            self.startup.problems.append(Problem(exc.code, exc.message))
+
+        # 4.1: a one-off GUI result is cleaned up when the app exits
+        # normally, and a forced termination leaves the rest behind.  What
+        # survives here is only what the sweep above did not claim, so it
+        # is scratch by definition.
+        self.startup.temp_entries_removed = clear_temp_tree(temp_dir())
+
+    def _ensure_owner_credential(self) -> None:
+        """F-71 and N-31.
+
+        The service listens from first launch, so a credential has to exist
+        from first launch -- and it must be minted here rather than shipped,
+        because a distribution containing one would be a well-known
+        credential, which N-31 forbids outright.
+        """
+        if self.credentials.owner_credential() is not None:
+            return
+        try:
+            issued = self.credentials.issue(
+                name="EchoAct (this computer)",
+                capabilities={Capability.OWNER},
+                days=self.settings.credential_days,
+            )
+            self.startup.owner_credential = issued
+        except EchoActError as exc:
+            self.startup.problems.append(Problem(exc.code, exc.message))
+
+    # ------------------------------------------------------------------
+    # Scheduled backup (F-74, N-28)
+    # ------------------------------------------------------------------
+
+    def run_due_backup(self, now: float | None = None) -> Any:
+        """Take the daily backup if one is due.  Returns the outcome or None.
+
+        Called on a timer by whoever owns one, and never on the Qt main
+        thread: a backup copies the whole library.  Everything F-74 asks
+        for is decided inside the scheduler -- once a day, only while the
+        app is running, deferred during generation and during a restore, a
+        missed schedule made up once rather than accumulating -- so this is
+        only the tick and the two facts the scheduler cannot see for
+        itself: whether a job is running, and where the owner wants it.
+
+        N-28 puts a scheduled backup behind the user's generation and
+        playback, which is why ``generating`` is passed rather than
+        inferred: deferring is the scheduler's decision, but knowing is
+        this object's.
+        """
+        settings = self.settings
+        if not settings.scheduled_backup:
+            return None
+        try:
+            return self.scheduler.run_due(
+                self.store,
+                ids.now() if now is None else now,
+                enabled=True,
+                location=settings.scheduled_backup_location,
+                generating=self.engine.busy,
+            )
+        except EchoActError as exc:
+            # F-70 notifies a backup failure; it is never a reason to stop.
+            log.warning("scheduled backup: %s", exc.code.value)
+            self.startup.problems.append(Problem(exc.code, exc.message))
+            return None
+
+    # ------------------------------------------------------------------
+    # Settings
+    # ------------------------------------------------------------------
+
+    def update_settings(self, **changes: Any) -> Settings:
+        """Change settings and tell everyone who cares.
+
+        F-78: the running job is untouched.  It recorded the budget it
+        started under, and nothing here reaches into it.
+        """
+        self.settings = self.settings.with_(**changes)
+        self.settings_store.save(self.settings)
+        self.engine.apply_settings(self.settings)
+        self.store.set_retention_limit(self.settings.retention_bytes)
+        return self.settings
+
+    # ------------------------------------------------------------------
+    # Model preparation (F-09, N-11, F-80)
+    # ------------------------------------------------------------------
+
+    def licence_pending(self, model_id: str | None = None) -> str | None:
+        """The model whose terms have not been accepted, if any.
+
+        N-11 makes acceptance a condition of first preparation, so the
+        window asks this before it starts a job rather than letting the
+        engine refuse one and reporting a code.
+        """
+        target = model_id or self.settings.voice.model_id
+        return target if self.registry.license_acceptance_required(target) else None
+
+    def accept_licence(self, model_id: str) -> None:
+        """Record that the owner accepted this model's restrictions.
+
+        Recorded against a fingerprint of the terms themselves, so a
+        release that amends them asks again instead of inheriting consent
+        given to different words.
+        """
+        self.registry.accept_license(model_id)
+        self.settings = self.settings_store.load()
+        self.engine.apply_settings(self.settings)
+
+    # ------------------------------------------------------------------
+    # The local service (F-46, F-79, N-31)
+    # ------------------------------------------------------------------
+
+    def start_service(self) -> Problem | None:
+        """Start the REST service if the owner has it on.
+
+        Returns a problem instead of raising.  F-79 is explicit that a bind
+        failure disables the integrations only and must be shown as an
+        actionable notice rather than a startup failure, so this cannot be
+        allowed to propagate.
+        """
+        if not self.settings.rest_enabled:
+            return None
+        try:
+            from .service.server import ServiceRunner
+
+            self.service = ServiceRunner(self)
+            self.service.start()
+            return None
+        except EchoActError as exc:
+            self.service = None
+            problem = Problem(exc.code, exc.message)
+            self.startup.problems.append(problem)
+            return problem
+        except Exception as exc:  # noqa: BLE001 - the GUI must still run
+            self.service = None
+            problem = Problem(
+                Code.SERVICE_PORT_UNAVAILABLE,
+                f"The local service could not start ({type(exc).__name__}).",
+            )
+            self.startup.problems.append(problem)
+            return problem
+
+    def stop_service(self) -> None:
+        if self.service is not None:
+            try:
+                self.service.stop()
+            finally:
+                self.service = None
+
+    @property
+    def service_running(self) -> bool:
+        return self.service is not None and getattr(self.service, "running", False)
+
+    # ------------------------------------------------------------------
+    # Shutdown (F-52, F-77)
+    # ------------------------------------------------------------------
+
+    def shutdown(self) -> None:
+        """Stop in the reverse order of construction.
+
+        The service first, so no new request can arrive while the engine is
+        being torn down; then the engine, which kills the worker; then
+        playback; and the database last, because everything above may want
+        to write a final row.
+        """
+        self.stop_service()
+        try:
+            self.engine.shutdown()
+        except Exception as exc:  # noqa: BLE001
+            log.warning("engine shutdown: %s", type(exc).__name__)
+        try:
+            self.player.close()
+        except Exception as exc:  # noqa: BLE001
+            log.warning("player shutdown: %s", type(exc).__name__)
+        try:
+            # 4.1: a GUI one-off result is cleaned up on a normal exit.
+            clear_temp_tree(temp_dir())
+        except OSError:
+            pass
+        self.store.close()

echoact/audio/devices.py

@@ -0,0 +1,192 @@
+"""Audio output devices: enumeration, selection, and loss.
+
+F-67 needs a device list the user can choose from, and requires that a
+device disappearing pauses playback rather than moving the sound to another
+speaker.  F-68 adds that after the machine resumes from sleep, the device
+list and the system resources are re-checked and playback is left paused.
+
+PortAudio caches its device list at initialisation, so a device plugged in
+or removed after start-up is invisible until the library is reinitialised.
+That is why :func:`refresh` exists and why it is called on resume rather
+than merely re-querying.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from ..errors import Code, EchoActError
+from ..util.logging import get_logger
+
+log = get_logger("audio.devices")
+
+
+@dataclass(frozen=True, slots=True)
+class OutputDevice:
+    index: int
+    name: str
+    host_api: str
+    max_channels: int
+    default_samplerate: float
+    is_default: bool
+
+    @property
+    def key(self) -> str:
+        """A stable-ish identifier to persist in settings.
+
+        PortAudio indices are positional and shift when devices come and
+        go, so a remembered index would silently select a different
+        speaker.  The name plus host API survives a reboot; the index does
+        not, and is resolved fresh each time.
+        """
+        return f"{self.host_api}::{self.name}"
+
+
+def _sd():
+    import sounddevice as sd
+
+    return sd
+
+
+def refresh() -> None:
+    """Re-read the device list from the operating system.
+
+    Needed after a resume (F-68) and after the user plugs something in;
+    without it PortAudio keeps answering from the list it built at start-up.
+    """
+    sd = _sd()
+    try:
+        sd._terminate()
+        sd._initialize()
+    except Exception as exc:  # noqa: BLE001 - a failed refresh is not fatal
+        log.warning("device refresh failed: %s", type(exc).__name__)
+
+
+def list_output_devices() -> list[OutputDevice]:
+    sd = _sd()
+    try:
+        devices = sd.query_devices()
+        apis = sd.query_hostapis()
+        default_index = sd.default.device[1]
+    except Exception as exc:  # noqa: BLE001
+        raise EchoActError(
+            Code.OUTPUT_DEVICE_UNAVAILABLE,
+            "The audio system could not be queried.",
+            cause=exc,
+        ) from exc
+
+    out: list[OutputDevice] = []
+    for i, d in enumerate(devices):
+        if int(d.get("max_output_channels", 0)) <= 0:
+            continue
+        api = apis[int(d.get("hostapi", 0))]["name"] if apis else ""
+        out.append(
+            OutputDevice(
+                index=i,
+                name=str(d.get("name", "")).strip(),
+                host_api=str(api),
+                max_channels=int(d["max_output_channels"]),
+                default_samplerate=float(d.get("default_samplerate", 0.0)),
+                is_default=(i == default_index),
+            )
+        )
+    return out
+
+
+def default_output_device() -> OutputDevice | None:
+    for d in list_output_devices():
+        if d.is_default:
+            return d
+    devices = list_output_devices()
+    return devices[0] if devices else None
+
+
+def resolve(key: str | None) -> OutputDevice | None:
+    """Find the remembered device, or report that it is gone.
+
+    Returning ``None`` for a key that no longer matches is deliberate: F-67
+    forbids switching to another speaker without the user's confirmation,
+    so the caller has to decide rather than being handed a substitute.
+    """
+    if not key:
+        return default_output_device()
+    for d in list_output_devices():
+        if d.key == key:
+            return d
+    return None
+
+
+def supports_rate(device_index: int, sample_rate: int) -> bool:
+    """Whether the device can take our output format.
+
+    F-82 forbids resampling, so a device that cannot accept the model's
+    native rate is a problem to report rather than to paper over.
+    """
+    sd = _sd()
+    try:
+        sd.check_output_settings(
+            device=device_index, channels=1, dtype="int16", samplerate=sample_rate
+        )
+        return True
+    except Exception:  # noqa: BLE001 - any refusal is a refusal
+        return False
+
+
+class DeviceWatcher:
+    """Polls for a change in the set of output devices.
+
+    Polling rather than an OS notification because the two supported
+    platforms signal this differently and neither reaches Python without a
+    native extension; the cost is one cheap query every few seconds, which
+    N-28 tolerates because it yields to nothing.
+    """
+
+    def __init__(
+        self,
+        on_change: Callable[[list[OutputDevice]], None],
+        *,
+        interval_s: float = 3.0,
+    ) -> None:
+        self._on_change = on_change
+        self._interval = interval_s
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._seen: tuple[str, ...] = ()
+
+    def start(self) -> None:
+        if self._thread is not None:
+            return
+        self._seen = self._snapshot()
+        self._thread = threading.Thread(target=self._run, name="echoact-devices", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        t, self._thread = self._thread, None
+        if t is not None:
+            t.join(timeout=2.0)
+
+    def _snapshot(self) -> tuple[str, ...]:
+        try:
+            return tuple(d.key for d in list_output_devices())
+        except EchoActError:
+            return ()
+
+    def _run(self) -> None:
+        while not self._stop.wait(self._interval):
+            current = self._snapshot()
+            if current == self._seen:
+                continue
+            # A change in the list is only trustworthy after a refresh;
+            # PortAudio would otherwise keep reporting the stale set.
+            refresh()
+            current = self._snapshot()
+            if current == self._seen:
+                continue
+            self._seen = current
+            try:
+                self._on_change(list_output_devices())
+            except Exception as exc:  # noqa: BLE001
+                log.warning("device change handler failed: %s", type(exc).__name__)