openspeechapi 0.1.0__py3-none-any.whl

openspeech/local_engines/base.py

@@ -0,0 +1,30 @@
+"""Abstractions for local engine backends."""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from openspeech.local_engines.models import EngineSpec, EngineStatus, RuntimeConfig
+
+
+class RuntimeBackend(ABC):
+    """Backend contract for local runtime operations (docker/native/etc)."""
+
+    runtime_name: str
+
+    @abstractmethod
+    def install(self, spec: EngineSpec, cfg: RuntimeConfig, report) -> None: ...
+
+    @abstractmethod
+    def update(self, spec: EngineSpec, cfg: RuntimeConfig, report) -> None: ...
+
+    @abstractmethod
+    def start(self, spec: EngineSpec, cfg: RuntimeConfig, report) -> None: ...
+
+    @abstractmethod
+    def stop(self, spec: EngineSpec, cfg: RuntimeConfig, report) -> None: ...
+
+    @abstractmethod
+    def status(self, spec: EngineSpec, cfg: RuntimeConfig) -> EngineStatus: ...
+
+    @abstractmethod
+    def logs(self, spec: EngineSpec, cfg: RuntimeConfig, lines: int = 100) -> str: ...

openspeech/local_engines/engines/__init__.py

@@ -0,0 +1 @@
+"""Engine spec definitions."""

openspeech/local_engines/engines/faster_whisper.py

@@ -0,0 +1,36 @@
+"""Faster-Whisper local model engine spec."""
+from __future__ import annotations
+
+from openspeech.local_engines.models import EngineSpec
+
+
+FASTER_WHISPER_SPEC = EngineSpec(
+    name="faster-whisper",
+    default_runtime="native",
+    description="Faster-Whisper local STT model assets",
+    options={
+        "native_model_only": True,
+        "native_install_script": "scripts/engines/faster-whisper/native/install.sh",
+        "native_model_dir": "models/faster-whisper",
+        "native_model_marker": "current",
+        "native_simulate_download": True,
+        "native_use_aim": True,
+        "native_aim_model_ids": [
+            "faster-whisper-large-v3-turbo",
+        ],
+        "native_aim_downloads": [
+            {
+                "model_id": "faster-whisper-large-v3-turbo",
+                "source": "hf:mobiuslabsgmbh/faster-whisper-large-v3-turbo",
+                "category": "asr",
+            }
+        ],
+        "native_aim_provision_engine": "whisper",
+        "native_aim_model_kind": "dir",
+        "native_existing_model_paths": [
+            "~/AI/whisper/faster-whisper-large-v3-turbo",
+            "~/AI/whisper/models--mobiuslabsgmbh--faster-whisper-large-v3-turbo",
+            "~/.cache/huggingface/hub/models--Systran--faster-whisper-large-v3-turbo",
+        ],
+    },
+)

openspeech/local_engines/engines/fish_speech.py

@@ -0,0 +1,33 @@
+"""Fish-Speech engine spec."""
+from __future__ import annotations
+
+from openspeech.local_engines.models import EngineSpec
+
+
+FISH_SPEECH_SPEC = EngineSpec(
+    name="fish-speech",
+    default_runtime="docker",
+    description="Fish-Speech local TTS engine",
+    options={
+        "docker_image": "fishaudio/fish-speech:latest",
+        "container_name": "openspeech-fish-speech",
+        "platform": "linux/amd64",
+        "container_port": 8080,
+        "host_port": 8080,
+        "health_path": "/health",
+        # Override this if your image requires a custom startup command.
+        "start_command": "",
+        # Native runtime defaults.
+        "native_repo_url": "https://github.com/fishaudio/fish-speech.git",
+        "native_repo_ref": "main",
+        "native_install_script": "scripts/engines/fish-speech/native/install.sh",
+        "native_install_target": ".[cpu]",
+        "native_device": "mps",
+        "native_model_repo": "fishaudio/s2-pro",
+        "native_model_dir": "checkpoints/s2-pro",
+        "native_hf_max_workers": 4,
+        "native_llama_checkpoint_path": "checkpoints/s2-pro",
+        "native_decoder_checkpoint_path": "checkpoints/s2-pro/codec.pth",
+        "native_decoder_config_name": "modded_dac_vq",
+    },
+)

openspeech/local_engines/engines/sherpa_onnx.py

@@ -0,0 +1,56 @@
+"""Sherpa-ONNX local STT engine spec."""
+from __future__ import annotations
+
+from openspeech.local_engines.models import EngineSpec
+
+
+SHERPA_ONNX_SPEC = EngineSpec(
+    name="sherpa-onnx",
+    default_runtime="native",
+    description="Sherpa-ONNX local streaming STT engine",
+    options={
+        "native_install_script": "scripts/engines/sherpa-onnx/native/install.sh",
+        "native_repo_url": "https://github.com/k2-fsa/sherpa-onnx.git",
+        "native_repo_ref": "master",
+        "native_model_only": False,
+        "native_model_dir": "models/sherpa-onnx",
+        "native_model_marker": "metadata.json",
+        "native_use_aim": True,
+        "native_aim_model_ids": [
+            "sherpa-onnx-paraformer-zh-en",
+            "sherpa-onnx-zipformer-zh-en",
+        ],
+        "native_aim_downloads": [
+            {
+                "model_id": "sherpa-onnx-zipformer-zh-en",
+                "source": "hf:csukuangfj/sherpa-onnx-streaming-zipformer-bilingual-zh-en-2023-02-20",
+                "category": "asr",
+            },
+            {
+                "model_id": "sherpa-onnx-paraformer-zh-en",
+                "source": "hf:k2-fsa/sherpa-onnx-paraformer-zh-en",
+                "category": "asr",
+            },
+        ],
+        "native_aim_provision_engine": "whisper",
+        "native_aim_model_kind": "dir",
+        "native_existing_model_paths": [
+            "~/AI/store/asr/model/sherpa-onnx-paraformer-zh-en",
+            "~/AI/store/asr/model/sherpa-onnx-zipformer-zh-en",
+        ],
+        "native_simulate_download": True,
+        "native_model_repo": "",
+        "native_start_cmd": [
+            "{venv_python}",
+            "{project_root}/scripts/engines/sherpa-onnx/native/run_streaming_server.py",
+            "--repo-dir",
+            "{repo_dir}",
+            "--host",
+            "{api_host}",
+            "--port",
+            "{api_port}",
+            "--model-dir",
+            "{model_dir}/current",
+        ],
+    },
+)

openspeech/local_engines/engines/whisper.py

@@ -0,0 +1,41 @@
+"""Whisper local model engine spec."""
+from __future__ import annotations
+
+from openspeech.local_engines.models import EngineSpec
+
+
+WHISPER_SPEC = EngineSpec(
+    name="whisper",
+    default_runtime="native",
+    description="OpenAI Whisper local STT model assets",
+    options={
+        "native_model_only": True,
+        "native_install_script": "scripts/engines/whisper/native/install.sh",
+        "native_model_dir": "models/whisper",
+        "native_model_marker": "current.pt",
+        "native_simulate_download": True,
+        "native_use_aim": True,
+        "native_aim_model_ids": [
+            "whisper-large-v3-turbo",
+            "whisper-large-v3",
+        ],
+        "native_aim_downloads": [
+            {
+                "model_id": "whisper-large-v3-turbo",
+                "source": "hf:openai/whisper-large-v3-turbo",
+                "category": "asr",
+            },
+            {
+                "model_id": "whisper-large-v3",
+                "source": "hf:openai/whisper-large-v3",
+                "category": "asr",
+            },
+        ],
+        "native_aim_provision_engine": "whisper",
+        "native_aim_model_kind": "file",
+        "native_existing_model_paths": [
+            "~/AI/whisper/large-v3-turbo.pt",
+            "~/AI/whisper/large-v3.pt",
+        ],
+    },
+)

openspeech/local_engines/engines/whisperlivekit.py

@@ -0,0 +1,60 @@
+"""WhisperLiveKit local STT engine spec."""
+from __future__ import annotations
+
+from openspeech.local_engines.models import EngineSpec
+
+
+WHISPERLIVEKIT_SPEC = EngineSpec(
+    name="whisperlivekit",
+    default_runtime="native",
+    description="WhisperLiveKit local streaming STT engine (mlx-whisper backend)",
+    options={
+        "native_install_script": "scripts/engines/whisperlivekit/native/install.sh",
+        "native_repo_url": "https://github.com/QuentinFuxa/WhisperLiveKit.git",
+        "native_repo_ref": "main",
+        "native_model_dir": "models/whisperlivekit",
+        "native_use_aim": True,
+        "native_aim_model_ids": [
+            "whisper-large-v3-turbo",
+            "whisper-large-v3",
+        ],
+        "native_aim_downloads": [
+            {
+                "model_id": "whisper-large-v3-turbo",
+                "source": "hf:openai/whisper-large-v3-turbo",
+                "category": "asr",
+            },
+            {
+                "model_id": "whisper-large-v3",
+                "source": "hf:openai/whisper-large-v3",
+                "category": "asr",
+            },
+        ],
+        "native_aim_provision_engine": "whisper",
+        "native_aim_model_kind": "file",
+        "native_existing_model_paths": [
+            "~/AI/whisper/large-v3-turbo.pt",
+            "~/AI/whisper/large-v3.pt",
+        ],
+        # Override with cfg.options.native_start_cmd if WhisperLiveKit CLI changes.
+        "native_start_cmd": [
+            "{service_dir}/.venv/bin/wlk",
+            "serve",
+            "--host",
+            "{api_host}",
+            "--port",
+            "{api_port}",
+            "--backend",
+            "mlx-whisper",
+            "--pcm-input",
+            "--no-vac",
+            "--no-vad",
+            "--min-chunk-size",
+            "0.2",
+            "--never-fire",
+            "--protocol-log",
+            "--protocol-log-max-chars",
+            "300",
+        ],
+    },
+)

openspeech/local_engines/manager.py

@@ -0,0 +1,208 @@
+"""Task-based local engine manager with progress events."""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+import threading
+from typing import Callable
+
+from openspeech.local_engines.backends.docker_backend import DockerBackend
+from openspeech.local_engines.backends.native_backend import NativeBackend
+from openspeech.local_engines.models import EngineAction, EngineStatus, RuntimeConfig, TaskStatus
+from openspeech.local_engines.progress import ProgressEmitter, ProgressEvent
+from openspeech.local_engines.registry import default_engine_registry
+from openspeech.local_engines.task_store import JsonTaskStore
+from openspeech.local_engines.tasks import EngineTask
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class _TaskCancelled(RuntimeError):
+    """Internal cancellation sentinel."""
+
+
+class EngineManager:
+    """Coordinates local engine actions with structured progress updates."""
+
+    def __init__(self) -> None:
+        self._engines = default_engine_registry()
+        self._backends = {
+            "docker": DockerBackend(),
+            "native": NativeBackend(),
+        }
+        self._tasks: dict[str, EngineTask] = {}
+        self._task_threads: dict[str, threading.Thread] = {}
+        self._lock = threading.Lock()
+        self._store = JsonTaskStore()
+        self.emitter = ProgressEmitter()
+
+    def _resolve_engine(self, name: str):
+        if name not in self._engines:
+            available = ", ".join(sorted(self._engines))
+            raise ValueError(f"Unknown engine '{name}'. Available: {available}")
+        return self._engines[name]
+
+    def _resolve_runtime(self, runtime: str):
+        if runtime not in self._backends:
+            available = ", ".join(sorted(self._backends))
+            raise ValueError(f"Unknown runtime '{runtime}'. Available: {available}")
+        return self._backends[runtime]
+
+    def _emit(self, task: EngineTask) -> None:
+        self._store.save(task)
+        self.emitter.emit(
+            ProgressEvent(
+                task_id=task.task_id,
+                engine=task.engine,
+                action=task.action.value,
+                runtime=task.runtime,
+                phase=task.phase,
+                message=task.message,
+                progress=task.progress,
+                eta_seconds=task.eta_seconds,
+                status=task.status,
+                metadata=dict(task.metadata),
+            )
+        )
+
+    def _raise_if_cancelled(self, task: EngineTask) -> None:
+        if bool(task.metadata.get("cancel_requested", False)):
+            raise _TaskCancelled("Task was cancelled by user.")
+
+    def _reporter(self, task: EngineTask) -> Callable:
+        def _report(
+            phase: str,
+            message: str,
+            progress: float | None = None,
+            *,
+            eta_seconds: int | None = None,
+        ) -> None:
+            self._raise_if_cancelled(task)
+            task.phase = phase
+            task.message = message
+            task.progress = progress
+            task.eta_seconds = eta_seconds
+            task.updated_at = _utc_now()
+            self._emit(task)
+
+        return _report
+
+    def _create_task(self, engine: str, action: EngineAction, runtime: str) -> EngineTask:
+        task = EngineTask(engine=engine, action=action, runtime=runtime)
+        with self._lock:
+            self._tasks[task.task_id] = task
+        self._emit(task)
+        return task
+
+    def get_task(self, task_id: str) -> EngineTask | None:
+        with self._lock:
+            if task_id in self._tasks:
+                return self._tasks[task_id]
+        return self._store.get(task_id)
+
+    def list_tasks(self, engine: str | None = None, limit: int = 20) -> list[EngineTask]:
+        return self._store.list(engine=engine, limit=limit)
+
+    def cancel_task(self, task_id: str) -> EngineTask | None:
+        task = self.get_task(task_id)
+        if task is None:
+            return None
+        if task.status in {TaskStatus.SUCCEEDED, TaskStatus.FAILED, TaskStatus.CANCELLED}:
+            return task
+        task.metadata["cancel_requested"] = True
+        task.phase = "cancel_requested"
+        task.message = "Cancellation requested. Waiting for safe stop point..."
+        task.updated_at = _utc_now()
+        self._emit(task)
+        return task
+
+    def _execute_task(self, task: EngineTask, cfg: RuntimeConfig) -> EngineTask:
+        spec = self._resolve_engine(task.engine)
+        backend = self._resolve_runtime(task.runtime)
+        self._raise_if_cancelled(task)
+
+        task.status = TaskStatus.RUNNING
+        task.phase = "starting"
+        task.message = f"{task.action.value} started."
+        task.progress = 0.0
+        task.updated_at = _utc_now()
+        self._emit(task)
+
+        report = self._reporter(task)
+        try:
+            if task.action == EngineAction.INSTALL:
+                backend.install(spec, cfg, report)
+            elif task.action == EngineAction.UPDATE:
+                backend.update(spec, cfg, report)
+            elif task.action == EngineAction.START:
+                backend.start(spec, cfg, report)
+            elif task.action == EngineAction.STOP:
+                backend.stop(spec, cfg, report)
+            else:
+                raise ValueError(f"Unsupported action: {task.action}")
+            task.status = TaskStatus.SUCCEEDED
+            task.phase = "completed"
+            task.message = f"{task.action.value} completed."
+            task.progress = 100.0
+            task.finished_at = _utc_now()
+            task.updated_at = task.finished_at
+            self._emit(task)
+            return task
+        except _TaskCancelled:
+            task.status = TaskStatus.CANCELLED
+            task.phase = "cancelled"
+            task.message = "Task cancelled by user."
+            task.error = None
+            task.finished_at = _utc_now()
+            task.updated_at = task.finished_at
+            self._emit(task)
+            return task
+        except Exception as exc:
+            task.status = TaskStatus.FAILED
+            task.phase = "failed"
+            task.message = str(exc)
+            task.error = str(exc)
+            task.finished_at = _utc_now()
+            task.updated_at = task.finished_at
+            self._emit(task)
+            raise
+
+    def run_action(self, engine: str, action: EngineAction, cfg: RuntimeConfig) -> EngineTask:
+        spec = self._resolve_engine(engine)
+        runtime = cfg.runtime or spec.default_runtime
+        task = self._create_task(engine=engine, action=action, runtime=runtime)
+        return self._execute_task(task, cfg)
+
+    def run_action_async(self, engine: str, action: EngineAction, cfg: RuntimeConfig) -> EngineTask:
+        spec = self._resolve_engine(engine)
+        runtime = cfg.runtime or spec.default_runtime
+        task = self._create_task(engine=engine, action=action, runtime=runtime)
+
+        def _worker() -> None:
+            try:
+                self._execute_task(task, cfg)
+            except Exception:
+                # _execute_task already records terminal state and error details.
+                pass
+            finally:
+                with self._lock:
+                    self._task_threads.pop(task.task_id, None)
+
+        t = threading.Thread(target=_worker, daemon=True)
+        with self._lock:
+            self._task_threads[task.task_id] = t
+        t.start()
+        return task
+
+    def status(self, engine: str, cfg: RuntimeConfig) -> EngineStatus:
+        spec = self._resolve_engine(engine)
+        runtime = cfg.runtime or spec.default_runtime
+        backend = self._resolve_runtime(runtime)
+        return backend.status(spec, cfg)
+
+    def logs(self, engine: str, cfg: RuntimeConfig, lines: int = 100) -> str:
+        spec = self._resolve_engine(engine)
+        runtime = cfg.runtime or spec.default_runtime
+        backend = self._resolve_runtime(runtime)
+        return backend.logs(spec, cfg, lines=lines)

openspeech/local_engines/models.py

@@ -0,0 +1,50 @@
+"""Models for local engine lifecycle management."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class TaskStatus(str, Enum):
+    QUEUED = "queued"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class EngineAction(str, Enum):
+    INSTALL = "install"
+    UPDATE = "update"
+    START = "start"
+    STOP = "stop"
+
+
+@dataclass
+class RuntimeConfig:
+    runtime: str = "docker"
+    api_url: str = "http://127.0.0.1:8080"
+    install_dir: str = "~/AI/services"
+    work_dir: str = ".openspeech/engines"
+    timeout_s: float = 120.0
+    retries: int = 0
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EngineSpec:
+    name: str
+    default_runtime: str = "docker"
+    description: str = ""
+    options: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EngineStatus:
+    engine: str
+    runtime: str
+    running: bool
+    healthy: bool
+    detail: str = ""
+    metadata: dict[str, Any] = field(default_factory=dict)

openspeech/local_engines/progress.py

@@ -0,0 +1,69 @@
+"""Progress events for long-running local engine operations."""
+from __future__ import annotations
+
+import queue
+import threading
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+from openspeech.local_engines.models import TaskStatus
+
+
+@dataclass
+class ProgressEvent:
+    task_id: str
+    engine: str
+    action: str
+    runtime: str
+    phase: str
+    message: str
+    status: TaskStatus
+    progress: float | None = None
+    eta_seconds: int | None = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class ProgressEmitter:
+    """In-process pub/sub emitter for progress events."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._watchers: dict[str, list[queue.Queue[ProgressEvent]]] = defaultdict(list)
+        self._global_watchers: list[queue.Queue[ProgressEvent]] = []
+
+    def subscribe(self, task_id: str) -> "queue.Queue[ProgressEvent]":
+        q: queue.Queue[ProgressEvent] = queue.Queue()
+        with self._lock:
+            self._watchers[task_id].append(q)
+        return q
+
+    def unsubscribe(self, task_id: str, q: "queue.Queue[ProgressEvent]") -> None:
+        with self._lock:
+            watchers = self._watchers.get(task_id, [])
+            if q in watchers:
+                watchers.remove(q)
+            if not watchers and task_id in self._watchers:
+                del self._watchers[task_id]
+
+    def subscribe_all(self) -> "queue.Queue[ProgressEvent]":
+        q: queue.Queue[ProgressEvent] = queue.Queue()
+        with self._lock:
+            self._global_watchers.append(q)
+        return q
+
+    def unsubscribe_all(self, q: "queue.Queue[ProgressEvent]") -> None:
+        with self._lock:
+            if q in self._global_watchers:
+                self._global_watchers.remove(q)
+
+    def emit(self, event: ProgressEvent) -> None:
+        with self._lock:
+            queues = list(self._watchers.get(event.task_id, []))
+            global_queues = list(self._global_watchers)
+        for q in queues:
+            q.put(event)
+        for q in global_queues:
+            q.put(event)

openspeech/local_engines/registry.py

@@ -0,0 +1,19 @@
+"""Engine registry for local runtime manager."""
+from __future__ import annotations
+
+from openspeech.local_engines.engines.faster_whisper import FASTER_WHISPER_SPEC
+from openspeech.local_engines.engines.fish_speech import FISH_SPEECH_SPEC
+from openspeech.local_engines.engines.sherpa_onnx import SHERPA_ONNX_SPEC
+from openspeech.local_engines.engines.whisper import WHISPER_SPEC
+from openspeech.local_engines.engines.whisperlivekit import WHISPERLIVEKIT_SPEC
+from openspeech.local_engines.models import EngineSpec
+
+
+def default_engine_registry() -> dict[str, EngineSpec]:
+    return {
+        FISH_SPEECH_SPEC.name: FISH_SPEECH_SPEC,
+        FASTER_WHISPER_SPEC.name: FASTER_WHISPER_SPEC,
+        WHISPER_SPEC.name: WHISPER_SPEC,
+        WHISPERLIVEKIT_SPEC.name: WHISPERLIVEKIT_SPEC,
+        SHERPA_ONNX_SPEC.name: SHERPA_ONNX_SPEC,
+    }

openspeech/local_engines/task_store.py

@@ -0,0 +1,52 @@
+"""Persistent task store for local engine operations."""
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+
+from openspeech.local_engines.tasks import EngineTask
+
+
+class JsonTaskStore:
+    """Stores each task as a JSON file for cross-process access."""
+
+    def __init__(self, root_dir: Path | None = None) -> None:
+        base = root_dir or (Path.home() / ".openspeech" / "engine_tasks")
+        self._dir = base.expanduser().resolve()
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def _path(self, task_id: str) -> Path:
+        return self._dir / f"{task_id}.json"
+
+    def save(self, task: EngineTask) -> None:
+        path = self._path(task.task_id)
+        payload = task.snapshot()
+        tmp = path.with_suffix(".tmp")
+        with self._lock:
+            tmp.write_text(json.dumps(payload, ensure_ascii=True, indent=2))
+            tmp.replace(path)
+
+    def get(self, task_id: str) -> EngineTask | None:
+        path = self._path(task_id)
+        if not path.exists():
+            return None
+        data = json.loads(path.read_text())
+        return EngineTask.from_snapshot(data)
+
+    def list(self, engine: str | None = None, limit: int = 20) -> list[EngineTask]:
+        files = sorted(self._dir.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+        tasks: list[EngineTask] = []
+        for p in files:
+            try:
+                data = json.loads(p.read_text())
+                task = EngineTask.from_snapshot(data)
+            except Exception:
+                continue
+            if engine and task.engine != engine:
+                continue
+            tasks.append(task)
+            if len(tasks) >= max(1, limit):
+                break
+        return tasks