openspeechapi 0.1.0__py3-none-any.whl

openspeech/__init__.py

@@ -0,0 +1,75 @@
+"""OpenSpeechAPI — Unified speech interface for STT/TTS providers."""
+
+__version__ = "0.1.0"
+
+from openspeech.config import load_config
+from openspeech.core.base import SpeechProvider, STTProvider, TTSProvider
+from openspeech.core.enums import AudioFormat, Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioChunk, AudioData, STTOptions, Transcription, TTSOptions, Word
+from openspeech.core.registry import ProviderRegistry
+from openspeech.core.settings import BaseSettings
+from openspeech.dispatch.context import InvokeContext
+from openspeech.dispatch.dispatcher import ServiceDispatcher
+from openspeech.client.client import Client
+from openspeech.factory import create_default_registry, create_provider, list_providers
+from openspeech.logging_config import (
+    bind_context,
+    configure_logging,
+    get_integration_tag,
+    get_log_settings,
+    integrate_with_host,
+    is_host_managed,
+    openspeech_filter,
+    openspeech_level_filter,
+)
+from openspeech.telemetry.perf import Event, PerfTimer, milestone
+from openspeech.utils import list_output_devices, play_audio
+from openspeech.exceptions import (
+    ConfigError,
+    FanOutAllFailedError,
+    OpenSpeechError,
+    ProviderCrashedError,
+    ProviderError,
+    ProviderNotFoundError,
+    ProviderUnavailableError,
+)
+
+def list_configured_engines(
+    config_path: "str | Path",
+    engine_type: str | None = None,
+) -> list[dict]:
+    """List configured engines from a config file (without starting providers).
+
+    Lightweight query: parses YAML + resolves catalog metadata only.
+    Suitable for populating UI dropdowns without running a full server.
+
+    Args:
+        config_path: Path to ``providers.yaml`` (or equivalent config file).
+        engine_type: Optional filter — ``"stt"``, ``"tts"``, or ``None`` for all.
+
+    Returns:
+        List of engine info dicts (same schema as
+        :py:meth:`ServiceDispatcher.list_engines_info`).
+    """
+    from pathlib import Path as _Path
+
+    registry = create_default_registry()
+    dispatcher = ServiceDispatcher.from_config(_Path(config_path), registry)
+    return dispatcher.list_engines_info(engine_type=engine_type)
+
+
+__all__ = [
+    "AudioChunk", "AudioData", "AudioFormat", "BaseSettings", "Capability",
+    "Client", "ConfigError", "Event", "ExecMode", "FanOutAllFailedError", "InvokeContext",
+    "PerfTimer",
+    "bind_context", "configure_logging", "get_integration_tag", "get_log_settings",
+    "integrate_with_host", "is_host_managed", "milestone",
+    "openspeech_filter", "openspeech_level_filter",
+    "create_default_registry", "create_provider", "list_configured_engines", "list_providers",
+    "OpenSpeechError", "ProviderCrashedError", "ProviderError",
+    "ProviderNotFoundError", "ProviderRegistry", "ProviderType",
+    "ProviderUnavailableError", "STTOptions", "STTProvider", "ServiceDispatcher",
+    "SpeechProvider", "TTSOptions", "TTSProvider", "Transcription", "Word",
+    "list_output_devices", "play_audio",
+    "load_config",
+]

openspeech/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m openspeech."""
+from openspeech.cli import main
+
+if __name__ == "__main__":
+    main()

openspeech/cli.py

@@ -0,0 +1,413 @@
+"""CLI entry point for OpenSpeech."""
+from __future__ import annotations
+import argparse
+import queue
+import sys
+import time
+from pathlib import Path
+from openspeech.config import load_config
+from openspeech.exceptions import ConfigError
+from openspeech.local_engines import EngineAction, EngineManager, RuntimeConfig
+from openspeech.local_engines.models import TaskStatus
+from openspeech.logging_config import configure_logging
+
+
+def _cmd_list(args: argparse.Namespace) -> None:
+    try:
+        config = load_config(Path(args.config))
+    except ConfigError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    if not config.engines:
+        print("No engines configured.")
+        return
+    print(f"{'Name':<25} {'Provider':<20} {'ExecMode':<15}")
+    print("-" * 60)
+    for name, eng in config.engines.items():
+        print(f"{name:<25} {eng.provider:<20} {eng.exec_mode:<15}")
+
+
+def _cmd_serve(args: argparse.Namespace) -> None:
+    """Start the OpenSpeech HTTP/WebSocket server."""
+    import uvicorn
+    from openspeech.server.app import create_app
+    config_path = Path(args.config)
+
+    # Build registry with all known providers (lazy imports via factory)
+    from openspeech.factory import create_default_registry
+    registry = create_default_registry()
+
+    app = create_app(config_path, registry)
+
+    config = load_config(config_path)
+    host = getattr(args, "host", None) or config.server.host
+    port = getattr(args, "port", None) or config.server.port
+    print(f"Starting OpenSpeech server on {host}:{port}")
+    uvicorn.run(app, host=host, port=port)
+
+
+def _cmd_check(args: argparse.Namespace) -> None:
+    try:
+        config = load_config(Path(args.config))
+        print(f"Config OK: {len(config.engines)} engine(s) configured.")
+    except ConfigError as e:
+        print(f"Config error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _runtime_cfg_from_args(args: argparse.Namespace) -> RuntimeConfig:
+    options = {}
+    if getattr(args, "image", None):
+        options["docker_image"] = args.image
+    if getattr(args, "container_name", None):
+        options["container_name"] = args.container_name
+    if getattr(args, "host_port", None):
+        options["host_port"] = int(args.host_port)
+    if getattr(args, "health_url", None):
+        options["health_url"] = args.health_url
+    if getattr(args, "model_repo", None):
+        options["native_model_repo"] = args.model_repo
+    if getattr(args, "simulate_download", None) is not None:
+        options["native_simulate_download"] = bool(args.simulate_download)
+    return RuntimeConfig(
+        runtime=getattr(args, "runtime", "docker"),
+        api_url=getattr(args, "api_url", "http://127.0.0.1:8080"),
+        install_dir=getattr(args, "install_dir", "~/AI/services") or "~/AI/services",
+        work_dir=getattr(args, "work_dir", ".openspeech/engines"),
+        timeout_s=float(getattr(args, "timeout", 120.0)),
+        retries=int(getattr(args, "retries", 0)),
+        options=options,
+    )
+
+
+def _print_progress_event(event) -> None:
+    progress = "--"
+    if event.progress is not None:
+        progress = f"{event.progress:>5.1f}%"
+    eta = "--:--"
+    if event.eta_seconds is not None:
+        s = max(0, int(event.eta_seconds))
+        h = s // 3600
+        m = (s % 3600) // 60
+        ss = s % 60
+        eta = f"{h:02d}:{m:02d}:{ss:02d}" if h > 0 else f"{m:02d}:{ss:02d}"
+    print(
+        f"[{event.task_id[:8]}] "
+        f"{event.action:<7} {event.phase:<14} {progress}  ETA {eta}  {event.message}"
+    )
+
+
+def _run_engine_action(
+    manager: EngineManager,
+    name: str,
+    action: EngineAction,
+    cfg: RuntimeConfig,
+    follow: bool = True,
+) -> None:
+    task = manager.run_action_async(name, action, cfg)
+    event_queue = manager.emitter.subscribe(task.task_id)
+    while True:
+        try:
+            evt = event_queue.get(timeout=0.2)
+        except queue.Empty:
+            latest = manager.get_task(task.task_id)
+            if latest and latest.status.value in {"succeeded", "failed", "cancelled"}:
+                break
+            continue
+        if follow:
+            _print_progress_event(evt)
+        if evt.status.value in {"succeeded", "failed", "cancelled"}:
+            break
+    manager.emitter.unsubscribe(task.task_id, event_queue)
+
+    task = manager.get_task(task.task_id)
+    if task is not None and task.status == TaskStatus.SUCCEEDED:
+        print(f"Task completed: {task.task_id}")
+    elif task is not None:
+        raise RuntimeError(task.error or f"Task failed: {task.task_id}")
+
+
+def _cmd_engine_task(args: argparse.Namespace, manager: EngineManager) -> None:
+    if args.engine_task_cmd == "status":
+        task = manager.get_task(args.task_id)
+        if task is None:
+            print(f"Task not found: {args.task_id}", file=sys.stderr)
+            sys.exit(1)
+        snap = task.snapshot()
+        keys = [
+            "task_id",
+            "engine",
+            "action",
+            "runtime",
+            "status",
+            "phase",
+            "progress",
+            "message",
+            "error",
+            "started_at",
+            "updated_at",
+            "finished_at",
+        ]
+        for k in keys:
+            print(f"{k}={snap.get(k)}")
+        return
+
+    if args.engine_task_cmd == "list":
+        tasks = manager.list_tasks(engine=args.name, limit=args.limit)
+        if not tasks:
+            print("No tasks.")
+            return
+        print(f"{'Task ID':<12} {'Engine':<12} {'Action':<8} {'Status':<10} {'Phase':<14} Message")
+        print("-" * 90)
+        for t in tasks:
+            msg = (t.message or "").replace("\n", " ")
+            print(
+                f"{t.task_id[:12]:<12} {t.engine:<12} {t.action.value:<8} "
+                f"{t.status.value:<10} {t.phase:<14} {msg}"
+            )
+        return
+
+    if args.engine_task_cmd == "follow":
+        deadline = time.monotonic() + max(1.0, args.timeout)
+        last_updated = ""
+        while time.monotonic() < deadline:
+            task = manager.get_task(args.task_id)
+            if task is None:
+                time.sleep(args.interval)
+                continue
+            stamp = task.updated_at.isoformat()
+            if stamp != last_updated:
+                progress = "--" if task.progress is None else f"{task.progress:>5.1f}%"
+                print(
+                    f"[{task.task_id[:8]}] {task.action.value:<7} {task.phase:<14} "
+                    f"{progress}  {task.message}"
+                )
+                last_updated = stamp
+            if task.status.value in {"succeeded", "failed", "cancelled"}:
+                return
+            time.sleep(args.interval)
+        print("Follow timeout reached.")
+        return
+
+    if args.engine_task_cmd == "cancel":
+        task = manager.cancel_task(args.task_id)
+        if task is None:
+            print(f"Task not found: {args.task_id}", file=sys.stderr)
+            sys.exit(1)
+        print(f"Cancellation requested: {task.task_id}")
+        return
+
+
+def _cmd_engine(args: argparse.Namespace) -> None:
+    manager = EngineManager()
+
+    try:
+        if args.engine_cmd == "task":
+            _cmd_engine_task(args, manager)
+            return
+
+        cfg = _runtime_cfg_from_args(args)
+        name = args.name
+        if args.engine_cmd == "status":
+            s = manager.status(name, cfg)
+            print(f"engine={s.engine}")
+            print(f"runtime={s.runtime}")
+            print(f"running={s.running}")
+            print(f"healthy={s.healthy}")
+            print(f"detail={s.detail}")
+            return
+        if args.engine_cmd == "logs":
+            out = manager.logs(name, cfg, lines=args.lines)
+            print(out or "(no logs)")
+            return
+
+        action_map = {
+            "install": EngineAction.INSTALL,
+            "update": EngineAction.UPDATE,
+            "start": EngineAction.START,
+            "stop": EngineAction.STOP,
+        }
+        if args.engine_cmd not in action_map:
+            raise ValueError(f"Unsupported engine command: {args.engine_cmd}")
+        _run_engine_action(
+            manager=manager,
+            name=name,
+            action=action_map[args.engine_cmd],
+            cfg=cfg,
+            follow=bool(args.follow),
+        )
+    except Exception as e:
+        print(f"Engine error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _load_dotenv() -> None:
+    """Load .env file if python-dotenv is available."""
+    try:
+        from dotenv import load_dotenv
+        load_dotenv()
+    except ImportError:
+        pass
+
+
+def _add_logging_args(parser: argparse.ArgumentParser) -> None:
+    """Register common logging flags on ``parser``.
+
+    Values left as ``None`` fall back to ``OPENSPEECH_LOG_*`` env vars,
+    then to built-in defaults in ``openspeech.logging_config``.
+    """
+    parser.add_argument(
+        "--log-level",
+        default=None,
+        choices=["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Log verbosity (env: OPENSPEECH_LOG_LEVEL). Default INFO.",
+    )
+    parser.add_argument(
+        "--log-format",
+        default=None,
+        choices=["text", "json"],
+        help="Console log format (env: OPENSPEECH_LOG_FORMAT). Default text.",
+    )
+    parser.add_argument(
+        "--log-dir",
+        default=None,
+        help=(
+            "Directory for rotating JSONL logs (env: OPENSPEECH_LOG_DIR). "
+            "Default 'logs'. Pass empty string to disable file logging."
+        ),
+    )
+    parser.add_argument(
+        "--log-perf",
+        default=None,
+        choices=["off", "basic", "verbose"],
+        help="Performance milestone verbosity (env: OPENSPEECH_LOG_PERF). Default basic.",
+    )
+
+
+def _apply_logging_args(args: argparse.Namespace) -> None:
+    """Apply parsed logging flags via ``configure_logging``."""
+    log_dir = getattr(args, "log_dir", None)
+    configure_logging(
+        level=getattr(args, "log_level", None),
+        format=getattr(args, "log_format", None),
+        log_dir=log_dir,  # None → env/default; "" → disabled
+        perf=getattr(args, "log_perf", None),
+    )
+
+
+def main(argv: list[str] | None = None) -> None:
+    _load_dotenv()
+    parser = argparse.ArgumentParser(prog="openspeech", description="OpenSpeech CLI")
+    parser.add_argument("--config", default="providers.yaml", help="Config file path")
+    _add_logging_args(parser)
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("list", help="List configured providers")
+    sub.add_parser("check", help="Validate configuration")
+    serve_p = sub.add_parser("serve", help="Start HTTP/WebSocket server")
+    serve_p.add_argument("--host", default="0.0.0.0", help="Bind host")
+    serve_p.add_argument("--port", type=int, default=8600, help="Bind port")
+
+    engine_p = sub.add_parser("engine", help="Manage local engine runtime")
+    engine_sub = engine_p.add_subparsers(dest="engine_cmd", required=True)
+
+    def _add_engine_common(p: argparse.ArgumentParser) -> None:
+        p.add_argument("--name", default="fish-speech", help="Engine name")
+        p.add_argument("--runtime", default="docker", choices=["docker", "native"])
+        p.add_argument("--api-url", default="http://127.0.0.1:8080")
+        p.add_argument(
+            "--install-dir",
+            default="~/AI/services",
+            help="Native services root directory",
+        )
+        p.add_argument("--work-dir", default=".openspeech/engines", help="Engine cache/work dir")
+        p.add_argument("--timeout", type=float, default=120.0, help="Operation timeout in seconds")
+        p.add_argument("--retries", type=int, default=0, help="Retry count")
+        p.add_argument("--image", default="", help="Docker image override")
+        p.add_argument("--container-name", default="", help="Docker container name override")
+        p.add_argument("--host-port", type=int, default=0, help="Host port override")
+        p.add_argument("--health-url", default="", help="Health URL override")
+        p.add_argument(
+            "--model-repo",
+            default="",
+            help="Native model repo id (e.g. Hugging Face model repo for sherpa-onnx)",
+        )
+        p.add_argument(
+            "--simulate-download",
+            action=argparse.BooleanOptionalAction,
+            default=None,
+            help="Whether to simulate model download if local/downloaded model is not found",
+        )
+
+    install_p = engine_sub.add_parser("install", help="Install local engine runtime")
+    _add_engine_common(install_p)
+    install_p.add_argument(
+        "--follow",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Show live progress (default: enabled)",
+    )
+
+    update_p = engine_sub.add_parser("update", help="Update local engine runtime")
+    _add_engine_common(update_p)
+    update_p.add_argument(
+        "--follow",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Show live progress (default: enabled)",
+    )
+
+    start_p = engine_sub.add_parser("start", help="Start local engine runtime")
+    _add_engine_common(start_p)
+    start_p.add_argument(
+        "--follow",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Show live progress (default: enabled)",
+    )
+
+    stop_p = engine_sub.add_parser("stop", help="Stop local engine runtime")
+    _add_engine_common(stop_p)
+    stop_p.add_argument(
+        "--follow",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="Show live progress (default: enabled)",
+    )
+
+    status_p = engine_sub.add_parser("status", help="Get runtime status")
+    _add_engine_common(status_p)
+
+    logs_p = engine_sub.add_parser("logs", help="Show engine logs")
+    _add_engine_common(logs_p)
+    logs_p.add_argument("--lines", type=int, default=100, help="Tail line count")
+
+    task_p = engine_sub.add_parser("task", help="Inspect engine tasks")
+    task_sub = task_p.add_subparsers(dest="engine_task_cmd", required=True)
+    task_status_p = task_sub.add_parser("status", help="Get task details")
+    task_status_p.add_argument("--task-id", required=True, help="Task ID")
+    task_list_p = task_sub.add_parser("list", help="List recent tasks")
+    task_list_p.add_argument("--name", default=None, help="Filter by engine name")
+    task_list_p.add_argument("--limit", type=int, default=20, help="Max rows")
+    task_follow_p = task_sub.add_parser("follow", help="Poll task updates")
+    task_follow_p.add_argument("--task-id", required=True, help="Task ID")
+    task_follow_p.add_argument("--interval", type=float, default=1.0, help="Poll interval (seconds)")
+    task_follow_p.add_argument("--timeout", type=float, default=600.0, help="Max follow time (seconds)")
+    task_cancel_p = task_sub.add_parser("cancel", help="Request cancellation for a task")
+    task_cancel_p.add_argument("--task-id", required=True, help="Task ID")
+
+    args = parser.parse_args(argv)
+    _apply_logging_args(args)
+    if args.command is None:
+        parser.print_help()
+        return
+    commands = {
+        "list": _cmd_list,
+        "check": _cmd_check,
+        "serve": _cmd_serve,
+        "engine": _cmd_engine,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

openspeech/client/__init__.py

@@ -0,0 +1,4 @@
+"""OpenSpeech Python thin client."""
+from openspeech.client.client import Client
+
+__all__ = ["Client"]

openspeech/client/client.py

@@ -0,0 +1,145 @@
+"""Python thin client for OpenSpeech HTTP/WebSocket server."""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from openspeech.core.enums import AudioFormat
+from openspeech.core.models import AudioData, AudioChunk, STTOptions, TTSOptions, Transcription, Word
+
+
+class _ClientSTT:
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    async def transcribe(
+        self, provider: str, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription:
+        opts = opts or STTOptions()
+        data = {"provider": provider}
+        if opts.language:
+            data["language"] = opts.language
+        if opts.prompt:
+            data["prompt"] = opts.prompt
+        if opts.temperature is not None:
+            data["temperature"] = str(opts.temperature)
+        if opts.model:
+            data["model"] = opts.model
+        if opts.device:
+            data["device"] = opts.device
+        if opts.beam_size is not None:
+            data["beam_size"] = str(opts.beam_size)
+        if opts.compute_type:
+            data["compute_type"] = opts.compute_type
+        if opts.fp16 is not None:
+            data["fp16"] = str(bool(opts.fp16)).lower()
+
+        files = {"audio": ("audio.wav", audio.data, "audio/wav")}
+        resp = await self._client._http.post(
+            f"{self._client._base_url}/v1/stt/transcribe",
+            data=data, files=files,
+        )
+        resp.raise_for_status()
+        j = resp.json()
+
+        words = None
+        if j.get("words"):
+            words = [Word(text=w["text"], start_ms=w["start_ms"], end_ms=w["end_ms"],
+                         confidence=w.get("confidence")) for w in j["words"]]
+
+        return Transcription(
+            text=j["text"],
+            language=j.get("language"),
+            confidence=j.get("confidence"),
+            words=words,
+            duration_ms=j.get("duration_ms"),
+        )
+
+    async def fanout(
+        self, providers: list[str], audio: AudioData,
+        opts: STTOptions | None = None, strategy: str = "first_completed",
+    ) -> Any:
+        opts = opts or STTOptions()
+        data = {
+            "providers": ",".join(providers),
+            "strategy": strategy,
+        }
+        if opts.language:
+            data["language"] = opts.language
+        if opts.model:
+            data["model"] = opts.model
+        if opts.device:
+            data["device"] = opts.device
+        if opts.beam_size is not None:
+            data["beam_size"] = str(opts.beam_size)
+
+        files = {"audio": ("audio.wav", audio.data, "audio/wav")}
+        resp = await self._client._http.post(
+            f"{self._client._base_url}/v1/stt/transcribe/fanout",
+            data=data, files=files,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+class _ClientTTS:
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    async def synthesize(
+        self, provider: str, text: str, opts: TTSOptions | None = None
+    ) -> AudioData:
+        opts = opts or TTSOptions()
+        body = {"text": text, "provider": provider}
+        if opts.voice:
+            body["voice"] = opts.voice
+        if opts.speed != 1.0:
+            body["speed"] = opts.speed
+
+        resp = await self._client._http.post(
+            f"{self._client._base_url}/v1/tts/synthesize",
+            json=body,
+        )
+        resp.raise_for_status()
+
+        sample_rate = int(resp.headers.get("X-Sample-Rate", "16000"))
+        return AudioData(
+            data=resp.content,
+            sample_rate=sample_rate,
+            channels=1,
+            format=AudioFormat.WAV,
+        )
+
+
+class Client:
+    """OpenSpeech HTTP client — same interface as ServiceDispatcher."""
+
+    def __init__(self, base_url: str, timeout: float = 30.0) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._http = httpx.AsyncClient(timeout=timeout)
+        self.stt = _ClientSTT(self)
+        self.tts = _ClientTTS(self)
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "Client":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def list_engines(self) -> list[dict]:
+        resp = await self._http.get(f"{self._base_url}/v1/engines")
+        resp.raise_for_status()
+        return resp.json()["engines"]
+
+    # Backward compatibility alias
+    async def list_providers(self) -> list[dict]:
+        return await self.list_engines()
+
+    async def health(self) -> dict:
+        resp = await self._http.get(f"{self._base_url}/v1/health")
+        resp.raise_for_status()
+        return resp.json()