openspeechapi 0.1.0__py3-none-any.whl

openspeech/local_engines/backends/native_backend.py

@@ -0,0 +1,902 @@
+"""Native runtime backend for local engine lifecycle."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import re
+import shlex
+import shutil
+import signal
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+from openspeech.local_engines.aim_resolver import resolve_aim_model_paths
+from openspeech.local_engines.base import RuntimeBackend
+from openspeech.local_engines.models import EngineSpec, EngineStatus, RuntimeConfig
+
+DEFAULT_NATIVE_ROOT = "~/AI/services"
+_ANSI_RE = re.compile(r"\x1B\[[0-?]*[ -/]*[@-~]")
+_TQDM_HINT_RE = re.compile(
+    r"(?:(?P<label>[^:\n]{1,80}):\s*)?"
+    r"(?P<pct>\d{1,3})%\|[^|]*\|\s*"
+    r"(?P<done>[0-9.]+[A-Za-z]*)/(?P<total>[0-9.]+[A-Za-z]*)\s*"
+    r"\[(?P<elapsed>\d{1,2}:\d{2}(?::\d{2})?)<(?P<eta>\d{1,2}:\d{2}(?::\d{2})?),\s*(?P<speed>[^\]]+)\]"
+)
+
+
+class NativeBackend(RuntimeBackend):
+    runtime_name = "native"
+
+    def _effective_options(self, spec: EngineSpec, cfg: RuntimeConfig) -> dict:
+        opts = dict(spec.options)
+        opts.update(cfg.options)
+        return opts
+
+    def _native_root(self, cfg: RuntimeConfig) -> Path:
+        root = (cfg.install_dir or "").strip() or DEFAULT_NATIVE_ROOT
+        return Path(root).expanduser().resolve()
+
+    @staticmethod
+    def _project_root() -> Path:
+        # .../openspeech/local_engines/backends/native_backend.py -> project root
+        return Path(__file__).resolve().parents[3]
+
+    def _service_dir(self, spec: EngineSpec, cfg: RuntimeConfig) -> Path:
+        return self._native_root(cfg) / spec.name
+
+    def _repo_dir(self, spec: EngineSpec, cfg: RuntimeConfig) -> Path:
+        return self._service_dir(spec, cfg) / "src"
+
+    def _venv_dir(self, spec: EngineSpec, cfg: RuntimeConfig) -> Path:
+        return self._service_dir(spec, cfg) / ".venv"
+
+    def _run_dir(self, spec: EngineSpec, cfg: RuntimeConfig) -> Path:
+        return self._service_dir(spec, cfg) / "run"
+
+    def _model_only_ready_file(self, spec: EngineSpec, cfg: RuntimeConfig) -> Path:
+        return self._run_dir(spec, cfg) / "model-only.ready"
+
+    def _log_file(self, spec: EngineSpec, cfg: RuntimeConfig) -> Path:
+        return self._run_dir(spec, cfg) / "native.log"
+
+    def _pid_file(self, spec: EngineSpec, cfg: RuntimeConfig) -> Path:
+        return self._run_dir(spec, cfg) / "native.pid"
+
+    def _ensure_binary(self, name: str) -> None:
+        if shutil.which(name) is None:
+            raise RuntimeError(f"Required command not found in PATH: {name}")
+
+    def _resolve_script_path(self, script_value: str) -> Path:
+        raw = (script_value or "").strip()
+        if not raw:
+            raise RuntimeError("script path is empty")
+        p = Path(raw).expanduser()
+        if p.is_absolute():
+            return p
+        return (self._project_root() / p).resolve()
+
+    def _resolve_hf_bin(self, opts: dict) -> str:
+        preferred = str(opts.get("native_hf_bin", "")).strip()
+        if preferred:
+            path = shutil.which(preferred) if "/" not in preferred else preferred
+            if path:
+                return path
+        for name in ("hf", "huggingface-cli"):
+            path = shutil.which(name)
+            if path:
+                return path
+        raise RuntimeError(
+            "Hugging Face CLI not found. Install `hf` or `huggingface-cli` to download model weights."
+        )
+
+    def _model_dir(self, spec: EngineSpec, cfg: RuntimeConfig, opts: dict) -> Path:
+        rel = str(opts.get("native_model_dir", "checkpoints/s2-pro")).strip()
+        p = Path(rel)
+        if p.is_absolute():
+            return p
+        if self._is_model_only(opts):
+            return self._service_dir(spec, cfg) / p
+        return self._repo_dir(spec, cfg) / p
+
+    @staticmethod
+    def _is_model_only(opts: dict) -> bool:
+        return bool(opts.get("native_model_only", False))
+
+    @staticmethod
+    def _stringify_paths(value: object) -> str:
+        if isinstance(value, str):
+            return value.strip()
+        if isinstance(value, (list, tuple)):
+            items = [str(x).strip() for x in value if str(x).strip()]
+            return ":".join(items)
+        return ""
+
+    def _existing_model_paths(self, opts: dict) -> str:
+        configured = opts.get("native_existing_model_paths", "")
+        merged: list[str] = []
+        seen: set[str] = set()
+
+        aim_enabled = bool(opts.get("native_use_aim", False))
+        if aim_enabled:
+            aim_model_ids = opts.get("native_aim_model_ids", [])
+            if isinstance(aim_model_ids, str):
+                aim_model_ids = [x.strip() for x in aim_model_ids.split(",") if x.strip()]
+            if not isinstance(aim_model_ids, list):
+                aim_model_ids = []
+            aim_kind = str(opts.get("native_aim_model_kind", "any")).strip() or "any"
+            aim_paths = resolve_aim_model_paths(
+                model_ids=[str(x) for x in aim_model_ids],
+                provision_engine=str(opts.get("native_aim_provision_engine", "whisper")).strip() or "whisper",
+                kind=aim_kind,
+            )
+            for p in aim_paths:
+                if p not in seen:
+                    seen.add(p)
+                    merged.append(p)
+
+        if isinstance(configured, str):
+            configured_list = [x.strip() for x in configured.split(":") if x.strip()]
+        elif isinstance(configured, (list, tuple)):
+            configured_list = [str(x).strip() for x in configured if str(x).strip()]
+        else:
+            configured_list = []
+        for p in configured_list:
+            if p not in seen:
+                seen.add(p)
+                merged.append(p)
+        return ":".join(merged)
+
+    @staticmethod
+    def _aim_model_ids(opts: dict) -> list[str]:
+        ids = opts.get("native_aim_model_ids", [])
+        if isinstance(ids, str):
+            return [x.strip() for x in ids.split(",") if x.strip()]
+        if isinstance(ids, list):
+            return [str(x).strip() for x in ids if str(x).strip()]
+        return []
+
+    @staticmethod
+    def _aim_download_specs(opts: dict) -> list[dict]:
+        raw = opts.get("native_aim_downloads", [])
+        if isinstance(raw, dict):
+            raw = [raw]
+        if not isinstance(raw, list):
+            return []
+        specs: list[dict] = []
+        for item in raw:
+            if isinstance(item, str):
+                specs.append({"source": item.strip()})
+                continue
+            if not isinstance(item, dict):
+                continue
+            source = str(item.get("source", "")).strip()
+            model_id = str(item.get("model_id", "")).strip()
+            category = str(item.get("category", "")).strip()
+            if not source:
+                continue
+            spec = {"source": source}
+            if model_id:
+                spec["model_id"] = model_id
+            if category:
+                spec["category"] = category
+            specs.append(spec)
+        return specs
+
+    @staticmethod
+    def _pick_aim_download_spec(model_id: str, specs: list[dict]) -> dict | None:
+        for s in specs:
+            sid = str(s.get("model_id", "")).strip()
+            if sid and sid == model_id:
+                return s
+        for s in specs:
+            if "model_id" not in s:
+                return s
+        return None
+
+    def _aim_download(self, source: str, model_id: str, category: str = "") -> tuple[bool, str]:
+        cmd = ["aim", "download", source, "--name", model_id]
+        if category:
+            cmd.extend(["--category", category])
+        proc = subprocess.run(  # noqa: S603
+            cmd,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        out = (proc.stdout or "").strip()
+        err = (proc.stderr or "").strip()
+        detail = "\n".join(x for x in [out, err] if x).strip()
+        if proc.returncode != 0:
+            return False, detail or f"aim download failed (exit={proc.returncode})"
+        return True, detail or "ok"
+
+    def _ensure_aim_models(self, opts: dict, report) -> None:
+        if not bool(opts.get("native_use_aim", False)):
+            return
+        model_ids = self._aim_model_ids(opts)
+        if not model_ids:
+            return
+        if shutil.which("aim") is None:
+            report("aim_download", "AIM is not installed; fallback to legacy model download flow.", 16)
+            return
+
+        provision_engine = str(opts.get("native_aim_provision_engine", "whisper")).strip() or "whisper"
+        kind = str(opts.get("native_aim_model_kind", "any")).strip() or "any"
+        specs = self._aim_download_specs(opts)
+        report("aim_download", "Checking model availability via AIM...", 14)
+
+        for mid in model_ids:
+            existing = resolve_aim_model_paths(
+                model_ids=[mid],
+                provision_engine=provision_engine,
+                kind=kind,
+            )
+            if existing:
+                report("aim_download", f"AIM model ready: {mid}", 16)
+                continue
+
+            spec = self._pick_aim_download_spec(mid, specs)
+            if not spec:
+                report("aim_download", f"AIM model missing for {mid}; no AIM source configured, fallback.", 16)
+                continue
+            source = str(spec.get("source", "")).strip()
+            category = str(spec.get("category", "")).strip()
+            report("aim_download", f"Downloading {mid} via AIM: {source}", 20)
+            ok, detail = self._aim_download(source=source, model_id=mid, category=category)
+            if not ok:
+                report("aim_download", f"AIM download failed for {mid}; fallback to legacy flow. {detail}", 22)
+                continue
+            existing = resolve_aim_model_paths(
+                model_ids=[mid],
+                provision_engine=provision_engine,
+                kind=kind,
+            )
+            if existing:
+                report("aim_download", f"AIM download completed: {mid}", 24)
+            else:
+                report("aim_download", f"AIM download finished but model still unresolved: {mid}. {detail}", 24)
+
+    def _model_assets_present(self, spec: EngineSpec, cfg: RuntimeConfig, opts: dict) -> bool:
+        model_dir = self._model_dir(spec, cfg, opts)
+        marker = str(opts.get("native_model_marker", "")).strip()
+        if marker:
+            p = Path(marker)
+            if not p.is_absolute():
+                p = model_dir / marker
+            return p.exists()
+        if not model_dir.exists():
+            return False
+        return any(model_dir.iterdir())
+
+    @staticmethod
+    def _model_ready(model_dir: Path) -> bool:
+        return (model_dir / "codec.pth").exists() and (model_dir / "model.safetensors.index.json").exists()
+
+    def _download_model_weights(self, spec: EngineSpec, cfg: RuntimeConfig, opts: dict, report) -> None:
+        model_repo = str(opts.get("native_model_repo", "fishaudio/s2-pro")).strip()
+        model_dir = self._model_dir(spec, cfg, opts)
+        model_dir.parent.mkdir(parents=True, exist_ok=True)
+        if self._model_ready(model_dir):
+            report("download_model", f"Model weights already present: {model_dir}", 50)
+            return
+
+        hf_bin = self._resolve_hf_bin(opts)
+        report("download_model", f"Downloading model weights from {model_repo} ...", 50)
+        cmd = [hf_bin, "download", model_repo, "--local-dir", str(model_dir)]
+        max_workers = int(opts.get("native_hf_max_workers", 4) or 4)
+        if max_workers > 0:
+            cmd.extend(["--max-workers", str(max_workers)])
+        token = str(opts.get("native_hf_token", "")).strip()
+        if token:
+            cmd.extend(["--token", token])
+        self._run(cmd, cwd=self._repo_dir(spec, cfg))
+
+        if not self._model_ready(model_dir):
+            raise RuntimeError(
+                f"Model download did not produce expected files under {model_dir}."
+            )
+        report("download_model", f"Model weights downloaded to {model_dir}", 55)
+
+    def _python_version(self, python_bin: str) -> tuple[int, int, int]:
+        proc = subprocess.run(
+            [
+                python_bin,
+                "-c",
+                "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}')",
+            ],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if proc.returncode != 0:
+            raise RuntimeError(f"Unable to inspect Python version for: {python_bin}")
+        raw = (proc.stdout or "").strip()
+        parts = raw.split(".")
+        if len(parts) < 2:
+            raise RuntimeError(f"Invalid Python version output from {python_bin}: {raw}")
+        major = int(parts[0])
+        minor = int(parts[1])
+        micro = int(parts[2]) if len(parts) > 2 and parts[2].isdigit() else 0
+        return major, minor, micro
+
+    def _resolve_python_bin(self, opts: dict) -> str:
+        preferred = str(opts.get("native_python_bin", "")).strip()
+        candidates: list[str] = []
+        if preferred:
+            candidates.append(preferred)
+        candidates.extend(["python3.12", "python3.11", "python3.10", "python3.13", "python3"])
+
+        checked: list[str] = []
+        for name in candidates:
+            path = shutil.which(name) if "/" not in name else name
+            if not path:
+                continue
+            if path in checked:
+                continue
+            checked.append(path)
+            try:
+                major, minor, _ = self._python_version(path)
+            except Exception:
+                continue
+            if major == 3 and minor >= 10:
+                return path
+        tried = ", ".join(candidates)
+        raise RuntimeError(
+            "No compatible Python interpreter found for native install. "
+            f"Need Python >=3.10; tried: {tried}"
+        )
+
+    def _venv_python(self, spec: EngineSpec, cfg: RuntimeConfig) -> Path:
+        return self._venv_dir(spec, cfg) / "bin" / "python"
+
+    def _ensure_venv_compatible(self, spec: EngineSpec, cfg: RuntimeConfig, python_bin: str, report) -> None:
+        venv_dir = self._venv_dir(spec, cfg)
+        venv_python = self._venv_python(spec, cfg)
+        if not venv_python.exists():
+            report("create_venv", f"Creating virtualenv at {venv_dir} ...", 42)
+            self._run([python_bin, "-m", "venv", str(venv_dir)])
+            return
+        major, minor, _ = self._python_version(str(venv_python))
+        if major == 3 and minor >= 10:
+            report("create_venv", f"Virtualenv already exists: {venv_dir}", 42)
+            return
+        report("create_venv", f"Recreating incompatible virtualenv at {venv_dir} ...", 42)
+        shutil.rmtree(venv_dir, ignore_errors=True)
+        self._run([python_bin, "-m", "venv", str(venv_dir)])
+
+    def _run(self, cmd: list[str], cwd: Path | None = None) -> subprocess.CompletedProcess:
+        proc = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, check=False)
+        if proc.returncode != 0:
+            out = (proc.stdout or "").strip()
+            err = (proc.stderr or "").strip()
+            detail = "\n".join(x for x in [out, err] if x)
+            if detail:
+                raise RuntimeError(f"Command failed: {' '.join(cmd)}\n{detail}")
+            raise RuntimeError(f"Command failed: {' '.join(cmd)} (exit={proc.returncode})")
+        return proc
+
+    def _run_script_with_progress(
+        self,
+        script_path: Path,
+        *,
+        cwd: Path,
+        env: dict[str, str],
+        report,
+    ) -> None:
+        if not script_path.exists():
+            raise RuntimeError(f"Install script not found: {script_path}")
+
+        proc = subprocess.Popen(  # noqa: S603
+            ["/bin/bash", str(script_path)],
+            cwd=cwd,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+        if proc.stdout is None:
+            raise RuntimeError("Failed to capture install script output")
+
+        phase_re = re.compile(r"^OPENSPEECH_PHASE:([^:]+):([0-9]+(?:\.[0-9]+)?):(.*)$")
+        tail: list[str] = []
+        for line in proc.stdout:
+            s = line.rstrip("\n")
+            if not s:
+                continue
+            tail.append(s)
+            if len(tail) > 60:
+                tail.pop(0)
+            m = phase_re.match(s)
+            if m:
+                phase = m.group(1).strip()
+                progress = float(m.group(2))
+                message = m.group(3).strip()
+                report(phase, message, progress)
+
+        returncode = proc.wait()
+        if returncode != 0:
+            detail = "\n".join(tail)
+            raise RuntimeError(
+                f"Command failed: /bin/bash {script_path}\n{detail}"
+            )
+
+    def _run_install_script(
+        self,
+        spec: EngineSpec,
+        cfg: RuntimeConfig,
+        opts: dict,
+        report,
+        *,
+        action: str,
+    ) -> bool:
+        install_script = str(opts.get("native_install_script", "")).strip()
+        if not install_script:
+            return False
+        script_path = self._resolve_script_path(install_script)
+        python_bin = self._resolve_python_bin(opts)
+        root = self._native_root(cfg)
+        service_dir = self._service_dir(spec, cfg)
+        repo_dir = self._repo_dir(spec, cfg)
+        hf_bin = ""
+        try:
+            hf_bin = self._resolve_hf_bin(opts)
+        except Exception:
+            hf_bin = ""
+        model_dir = self._model_dir(spec, cfg, opts)
+        env = dict(os.environ)
+        env.update(
+            {
+                "OPENSPEECH_ACTION": action,
+                "OPENSPEECH_ENGINE": spec.name,
+                "OPENSPEECH_NATIVE_ROOT": str(root),
+                "OPENSPEECH_SERVICE_DIR": str(service_dir),
+                "OPENSPEECH_REPO_DIR": str(repo_dir),
+                "OPENSPEECH_VENV_DIR": str(self._venv_dir(spec, cfg)),
+                "OPENSPEECH_REPO_URL": str(
+                    opts.get("native_repo_url", "https://github.com/fishaudio/fish-speech.git")
+                ),
+                "OPENSPEECH_REPO_REF": str(opts.get("native_repo_ref", "main")),
+                "OPENSPEECH_PYTHON_BIN": python_bin,
+                "OPENSPEECH_HF_BIN": hf_bin,
+                "OPENSPEECH_HF_MAX_WORKERS": str(int(opts.get("native_hf_max_workers", 4) or 4)),
+                "OPENSPEECH_MODEL_REPO": str(opts.get("native_model_repo", "fishaudio/s2-pro")),
+                "OPENSPEECH_MODEL_DIR": str(model_dir),
+                "OPENSPEECH_INSTALL_TARGET": str(opts.get("native_install_target", ".[cpu]")),
+                "OPENSPEECH_EXISTING_MODEL_PATHS": self._existing_model_paths(opts),
+                "OPENSPEECH_SIMULATE_DOWNLOAD": str(
+                    int(bool(opts.get("native_simulate_download", True)))
+                ),
+            }
+        )
+        hf_token = str(opts.get("native_hf_token", "")).strip()
+        if hf_token:
+            env["OPENSPEECH_HF_TOKEN"] = hf_token
+        report("run_install_script", f"Running install script: {script_path}", 18)
+        self._run_script_with_progress(
+            script_path,
+            cwd=self._project_root(),
+            env=env,
+            report=report,
+        )
+        report("done", f"Native runtime installed under {service_dir}", 100)
+        return True
+
+    @staticmethod
+    def _is_pid_running(pid: int) -> bool:
+        if pid <= 0:
+            return False
+        try:
+            os.kill(pid, 0)
+            return True
+        except OSError:
+            return False
+
+    def _read_pid(self, pid_path: Path) -> int | None:
+        if not pid_path.exists():
+            return None
+        try:
+            return int(pid_path.read_text(encoding="utf-8").strip())
+        except Exception:
+            return None
+
+    @staticmethod
+    def _tail_file(path: Path, lines: int) -> str:
+        if lines <= 0 or not path.exists():
+            return ""
+        with path.open("r", encoding="utf-8", errors="ignore") as f:
+            all_lines = f.readlines()
+        return "".join(all_lines[-lines:]).strip()
+
+    @staticmethod
+    def _sanitize_log_line(line: str, max_len: int = 220) -> str:
+        clean = _ANSI_RE.sub("", line).strip()
+        if len(clean) <= max_len:
+            return clean
+        return clean[: max_len - 3] + "..."
+
+    def _read_log_hint(self, log_path: Path, cursor: int) -> tuple[int, str | None]:
+        if not log_path.exists():
+            return cursor, None
+        with log_path.open("r", encoding="utf-8", errors="ignore") as f:
+            f.seek(cursor)
+            chunk = f.read()
+            new_cursor = f.tell()
+        if not chunk:
+            return new_cursor, None
+        lines = [
+            self._sanitize_log_line(x)
+            for x in chunk.replace("\r", "\n").split("\n")
+            if x.strip()
+        ]
+        if not lines:
+            return new_cursor, None
+        return new_cursor, lines[-1]
+
+    @staticmethod
+    def _parse_time_to_seconds(raw: str) -> int | None:
+        txt = (raw or "").strip()
+        if not txt:
+            return None
+        parts = txt.split(":")
+        if len(parts) not in {2, 3}:
+            return None
+        try:
+            nums = [int(x) for x in parts]
+        except ValueError:
+            return None
+        if len(nums) == 2:
+            mm, ss = nums
+            return max(0, mm * 60 + ss)
+        hh, mm, ss = nums
+        return max(0, hh * 3600 + mm * 60 + ss)
+
+    def _summarize_log_hint(self, hint: str) -> tuple[str, float | None, int | None]:
+        m = _TQDM_HINT_RE.search(hint)
+        if not m:
+            return hint, None, None
+        pct = max(0.0, min(100.0, float(m.group("pct"))))
+        done = m.group("done")
+        total = m.group("total")
+        speed = m.group("speed").strip()
+        eta_txt = m.group("eta")
+        label = (m.group("label") or "").strip()
+        if label:
+            msg = f"{label}: {pct:.1f}% ({done}/{total}), {speed}, ETA {eta_txt}"
+        else:
+            msg = f"download: {pct:.1f}% ({done}/{total}), {speed}, ETA {eta_txt}"
+        return msg, pct, self._parse_time_to_seconds(eta_txt)
+
+    @staticmethod
+    def _is_fatal_log_hint(hint: str) -> bool:
+        text = (hint or "").strip().lower()
+        if not text:
+            return False
+        fatal_markers = (
+            "traceback (most recent call last)",
+            "runtimeerror:",
+            "module not found",
+            "no module named",
+            "failed to bind",
+            "address already in use",
+            "permission denied",
+        )
+        return any(m in text for m in fatal_markers)
+
+    @staticmethod
+    def _parse_listen_from_api_url(api_url: str) -> tuple[str, int]:
+        u = urllib.parse.urlparse(api_url)
+        host = u.hostname or "127.0.0.1"
+        if u.port is not None:
+            return host, int(u.port)
+        if u.scheme == "https":
+            return host, 443
+        return host, 8080
+
+    @staticmethod
+    def _check_http_alive(url: str) -> bool:
+        try:
+            with urllib.request.urlopen(url, timeout=2) as resp:
+                return resp.status < 500
+        except urllib.error.HTTPError as exc:
+            return exc.code < 500
+        except Exception:
+            return False
+
+    def _start_cmd(self, spec: EngineSpec, cfg: RuntimeConfig, opts: dict) -> list[str]:
+        venv_python = self._venv_python(spec, cfg)
+        if not venv_python.exists():
+            raise RuntimeError(
+                "Python virtualenv is not ready. Run install first for native runtime."
+            )
+        host, port = self._parse_listen_from_api_url(cfg.api_url)
+        custom = opts.get("native_start_cmd")
+        if custom:
+            if isinstance(custom, str):
+                parts = shlex.split(custom)
+            elif isinstance(custom, (list, tuple)):
+                parts = [str(x) for x in custom]
+            else:
+                raise RuntimeError("native_start_cmd must be a string or list")
+            variables = {
+                "venv_python": str(venv_python),
+                "api_host": host,
+                "api_port": str(port),
+                "api_url": cfg.api_url,
+                "project_root": str(self._project_root()),
+                "service_dir": str(self._service_dir(spec, cfg)),
+                "repo_dir": str(self._repo_dir(spec, cfg)),
+                "model_dir": str(self._model_dir(spec, cfg, opts)),
+            }
+            rendered = []
+            for p in parts:
+                try:
+                    rendered.append(p.format(**variables))
+                except Exception:
+                    rendered.append(p)
+            return rendered
+        cmd = [
+            str(venv_python),
+            "tools/api_server.py",
+            "--listen",
+            f"{host}:{port}",
+            "--mode",
+            "tts",
+            "--device",
+            str(opts.get("native_device", "mps")),
+            "--llama-checkpoint-path",
+            str(opts.get("native_llama_checkpoint_path", "checkpoints/s2-pro")),
+            "--decoder-checkpoint-path",
+            str(opts.get("native_decoder_checkpoint_path", "checkpoints/s2-pro/codec.pth")),
+            "--decoder-config-name",
+            str(opts.get("native_decoder_config_name", "modded_dac_vq")),
+        ]
+        if bool(opts.get("native_half", False)):
+            cmd.append("--half")
+        if bool(opts.get("native_compile", False)):
+            cmd.append("--compile")
+        api_key = str(opts.get("native_api_key", "")).strip()
+        if api_key:
+            cmd.extend(["--api-key", api_key])
+        return cmd
+
+    def install(self, spec: EngineSpec, cfg: RuntimeConfig, report) -> None:
+        opts = self._effective_options(spec, cfg)
+        report("check_runtime", "Checking native runtime prerequisites...", 5)
+        if not self._is_model_only(opts):
+            self._ensure_binary("git")
+        python_bin = self._resolve_python_bin(opts)
+        report("check_runtime", f"Using Python: {python_bin}", 8)
+        self._ensure_aim_models(opts, report)
+
+        root = self._native_root(cfg)
+        service_dir = self._service_dir(spec, cfg)
+        repo_dir = self._repo_dir(spec, cfg)
+        report("prepare_dirs", f"Preparing native root: {root}", 12)
+        service_dir.mkdir(parents=True, exist_ok=True)
+
+        if self._run_install_script(spec, cfg, opts, report, action="install"):
+            return
+
+        repo_url = str(opts.get("native_repo_url", "https://github.com/fishaudio/fish-speech.git"))
+        repo_ref = str(opts.get("native_repo_ref", "main"))
+        if (repo_dir / ".git").exists():
+            report("clone_repo", f"Repository already exists: {repo_dir}", 25)
+        else:
+            report("clone_repo", f"Cloning repository from {repo_url} ...", 25)
+            self._run(
+                ["git", "clone", "--depth", "1", "--branch", repo_ref, repo_url, str(repo_dir)]
+            )
+
+        self._ensure_venv_compatible(spec, cfg, python_bin, report)
+        venv_python = self._venv_python(spec, cfg)
+
+        self._download_model_weights(spec, cfg, opts, report)
+
+        report("install_deps", "Installing Python dependencies (this may take a while)...", 58)
+        self._run([str(venv_python), "-m", "pip", "install", "--upgrade", "pip"])
+        install_target = str(opts.get("native_install_target", ".[cpu]"))
+        self._run([str(venv_python), "-m", "pip", "install", "-e", install_target], cwd=repo_dir)
+        report("done", f"Native runtime installed under {service_dir}", 100)
+
+    def update(self, spec: EngineSpec, cfg: RuntimeConfig, report) -> None:
+        opts = self._effective_options(spec, cfg)
+        self._ensure_aim_models(opts, report)
+        if self._is_model_only(opts) and self._run_install_script(spec, cfg, opts, report, action="update"):
+            return
+        python_bin = self._resolve_python_bin(opts)
+        report("check_runtime", "Checking native runtime prerequisites...", 10)
+        self._ensure_binary("git")
+        repo_dir = self._repo_dir(spec, cfg)
+        if not (repo_dir / ".git").exists():
+            raise RuntimeError(
+                f"Native source not found at {repo_dir}. Run install first."
+            )
+        report("update_repo", "Updating native source repository...", 30)
+        self._run(["git", "-C", str(repo_dir), "fetch", "--all", "--tags"])
+        self._run(["git", "-C", str(repo_dir), "pull", "--ff-only"])
+
+        report("update_deps", "Refreshing Python dependencies...", 70)
+        self._ensure_venv_compatible(spec, cfg, python_bin, report)
+        venv_python = self._venv_python(spec, cfg)
+        self._run([str(venv_python), "-m", "pip", "install", "--upgrade", "pip"])
+        self._run([str(venv_python), "-m", "pip", "install", "-e", ".[cpu]"], cwd=repo_dir)
+        report("done", "Native runtime update completed.", 100)
+
+    def start(self, spec: EngineSpec, cfg: RuntimeConfig, report) -> None:
+        opts = self._effective_options(spec, cfg)
+        if self._is_model_only(opts):
+            run_dir = self._run_dir(spec, cfg)
+            run_dir.mkdir(parents=True, exist_ok=True)
+            ready = self._model_only_ready_file(spec, cfg)
+            report("check_assets", "Checking local model assets...", 25)
+            if not self._model_assets_present(spec, cfg, opts):
+                raise RuntimeError(
+                    "Model assets not found. Run install first or configure existing model paths."
+                )
+            ready.write_text(str(int(time.time())), encoding="utf-8")
+            report("ready", "Model assets are ready (model-only engine).", 100)
+            return
+        report("check_runtime", "Checking native runtime prerequisites...", 8)
+        repo_dir = self._repo_dir(spec, cfg)
+        if not repo_dir.exists():
+            raise RuntimeError(
+                f"Native source not found at {repo_dir}. Run install first."
+            )
+
+        run_dir = self._run_dir(spec, cfg)
+        run_dir.mkdir(parents=True, exist_ok=True)
+        pid_file = self._pid_file(spec, cfg)
+        existing_pid = self._read_pid(pid_file)
+        if existing_pid is not None and self._is_pid_running(existing_pid):
+            report("ready", f"Native service already running (pid={existing_pid}).", 100)
+            return
+
+        log_path = self._log_file(spec, cfg)
+        cmd = self._start_cmd(spec, cfg, opts)
+        report("start_process", "Starting native API process...", 40)
+        with log_path.open("a", encoding="utf-8") as log_f:
+            log_f.write(
+                f"\n[{time.strftime('%Y-%m-%d %H:%M:%S')}] starting: {' '.join(cmd)}\n"
+            )
+            log_f.flush()
+            proc = subprocess.Popen(  # noqa: S603
+                cmd,
+                cwd=repo_dir,
+                stdout=log_f,
+                stderr=subprocess.STDOUT,
+                start_new_session=True,
+                text=True,
+            )
+        pid_file.write_text(str(proc.pid), encoding="utf-8")
+
+        report("wait_health", f"Waiting for native API health: {cfg.api_url}", 65)
+        deadline = time.monotonic() + max(cfg.timeout_s, 1.0)
+        next_heartbeat = 0.0
+        log_cursor = 0
+        last_log_hint: str | None = None
+        while time.monotonic() < deadline:
+            pid = self._read_pid(pid_file)
+            if pid is None or not self._is_pid_running(pid):
+                tail = self._tail_file(log_path, 40)
+                raise RuntimeError(
+                    "Native process exited unexpectedly.\n"
+                    + (tail or "No logs available.")
+                )
+            now = time.monotonic()
+            if now >= next_heartbeat:
+                total = max(cfg.timeout_s, 1.0)
+                elapsed = total - max(0.0, deadline - now)
+                ratio = min(1.0, max(0.0, elapsed / total))
+                progress = 65.0 + ratio * 30.0
+                log_cursor, hint = self._read_log_hint(log_path, log_cursor)
+                if hint:
+                    last_log_hint = hint
+                if last_log_hint:
+                    hint_text, hint_pct, hint_eta = self._summarize_log_hint(last_log_hint)
+                    if hint_pct is not None:
+                        progress = max(progress, 65.0 + hint_pct * 0.30)
+                    if self._is_fatal_log_hint(hint_text):
+                        tail = self._tail_file(log_path, 80)
+                        raise RuntimeError(
+                            "Native process reported a fatal error during startup.\n"
+                            + (tail or hint_text)
+                        )
+                    report(
+                        "wait_health",
+                        f"Waiting for native API at {cfg.api_url} ... {hint_text}",
+                        progress,
+                        eta_seconds=hint_eta,
+                    )
+                else:
+                    report(
+                        "wait_health",
+                        f"Waiting for native API at {cfg.api_url} ...",
+                        progress,
+                    )
+                next_heartbeat = now + 1.0
+            if self._check_http_alive(cfg.api_url):
+                report("ready", f"Native API is healthy: {cfg.api_url}", 100)
+                return
+            time.sleep(1.0)
+
+        raise RuntimeError(
+            f"Timed out waiting for native API at {cfg.api_url}. "
+            f"Check logs in {log_path}."
+        )
+
+    def stop(self, spec: EngineSpec, cfg: RuntimeConfig, report) -> None:
+        opts = self._effective_options(spec, cfg)
+        if self._is_model_only(opts):
+            self._model_only_ready_file(spec, cfg).unlink(missing_ok=True)
+            report("done", "Model-only engine marked as stopped.", 100)
+            return
+        report("stop_process", "Stopping native API process...", 50)
+        pid_file = self._pid_file(spec, cfg)
+        pid = self._read_pid(pid_file)
+        if pid is None:
+            report("done", "Native service is not running.", 100)
+            return
+        if not self._is_pid_running(pid):
+            pid_file.unlink(missing_ok=True)
+            report("done", "Native service was already stopped.", 100)
+            return
+        try:
+            os.killpg(pid, signal.SIGTERM)
+        except Exception:
+            os.kill(pid, signal.SIGTERM)
+
+        deadline = time.monotonic() + 10.0
+        while time.monotonic() < deadline:
+            if not self._is_pid_running(pid):
+                break
+            time.sleep(0.2)
+        if self._is_pid_running(pid):
+            try:
+                os.killpg(pid, signal.SIGKILL)
+            except Exception:
+                os.kill(pid, signal.SIGKILL)
+        pid_file.unlink(missing_ok=True)
+        report("done", "Native service stopped.", 100)
+
+    def status(self, spec: EngineSpec, cfg: RuntimeConfig) -> EngineStatus:
+        opts = self._effective_options(spec, cfg)
+        if self._is_model_only(opts):
+            ready = self._model_only_ready_file(spec, cfg).exists()
+            assets_ok = self._model_assets_present(spec, cfg, opts)
+            return EngineStatus(
+                engine=spec.name,
+                runtime=self.runtime_name,
+                running=ready,
+                healthy=assets_ok,
+                detail="ready(model-only)" if ready else "stopped(model-only)",
+                metadata={
+                    "root_dir": str(self._native_root(cfg)),
+                    "service_dir": str(self._service_dir(spec, cfg)),
+                    "model_dir": str(self._model_dir(spec, cfg, opts)),
+                    "ready_file": str(self._model_only_ready_file(spec, cfg)),
+                },
+            )
+        pid = self._read_pid(self._pid_file(spec, cfg))
+        running = pid is not None and self._is_pid_running(pid)
+        healthy = running and self._check_http_alive(cfg.api_url)
+        detail = "running" if running else "stopped"
+        return EngineStatus(
+            engine=spec.name,
+            runtime=self.runtime_name,
+            running=running,
+            healthy=healthy,
+            detail=detail,
+            metadata={
+                "pid": pid,
+                "root_dir": str(self._native_root(cfg)),
+                "service_dir": str(self._service_dir(spec, cfg)),
+                "log_file": str(self._log_file(spec, cfg)),
+            },
+        )
+
+    def logs(self, spec: EngineSpec, cfg: RuntimeConfig, lines: int = 100) -> str:
+        return self._tail_file(self._log_file(spec, cfg), lines)