voxedge 0.0.1a0__py3-none-any.whl

voxedge/__init__.py

@@ -0,0 +1,10 @@
+"""voxedge — edge-native real-time voice conversation library.
+
+Phase 1a: pure-Python foundation. Core stays importable with no CUDA / torch /
+tensorrt — heavy backends live behind optional extras.
+"""
+from __future__ import annotations
+
+__version__ = "0.0.1a0"
+
+__all__ = ["__version__"]

voxedge/artifacts/__init__.py

@@ -0,0 +1,48 @@
+"""Backend-agnostic runtime artifact manifest + env-free download helper.
+
+The package is
+pure-Python and env-free; ``huggingface_hub`` is an optional dependency only
+needed for the default network downloader (``voxedge[artifacts]``).
+
+Public API::
+
+    from voxedge.artifacts import (
+        load_manifest, parse_manifest, default_manifest_path,
+        resolve_artifact, ArtifactInstallResult,
+        ManifestError, ArtifactError,
+    )
+"""
+
+from __future__ import annotations
+
+from .download import (
+    DEFAULT_HF_ENDPOINT,
+    ArtifactError,
+    ArtifactInstallResult,
+    resolve_artifact,
+)
+from .manifest import (
+    SCHEMA_VERSION,
+    ArtifactFile,
+    ArtifactManifest,
+    ArtifactSpec,
+    ManifestError,
+    default_manifest_path,
+    load_manifest,
+    parse_manifest,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "DEFAULT_HF_ENDPOINT",
+    "ArtifactFile",
+    "ArtifactSpec",
+    "ArtifactManifest",
+    "ArtifactInstallResult",
+    "ManifestError",
+    "ArtifactError",
+    "parse_manifest",
+    "load_manifest",
+    "default_manifest_path",
+    "resolve_artifact",
+]

voxedge/artifacts/download.py

@@ -0,0 +1,213 @@
+"""Env-free, backend-agnostic artifact download + install helper.
+
+Generalises the RK-specific ``ensure_rk_artifacts`` prototype
+(``voxedge/backends/rk/artifacts.py``) into a backend-agnostic helper keyed by
+a stable ``artifact_ref``. The public entry point is :func:`resolve_artifact`,
+which:
+
+  1. looks up the artifact by ``artifact_ref`` in the manifest,
+  2. for each declared file, downloads it from the HF repo (or any injected
+     downloader) into ``install_root/<path>``,
+  3. verifies the SHA-256 of every file (already-present + correct files are
+     skipped),
+  4. fails loudly with :class:`ArtifactError` on a missing file or SHA mismatch
+     (preflight semantics — e.g. a missing ``style.npy`` voice pack must fail,
+     not silently produce silent audio),
+  5. returns an :class:`ArtifactInstallResult` recording what was installed vs
+     skipped.
+
+**Env-free**: every input is a function argument; nothing reads ``os.environ``.
+The install root is supplied by the caller (product / profile) — the manifest
+only stores artifact-relative paths.
+
+``huggingface_hub`` is an OPTIONAL dependency. The default downloader uses it,
+but tests (and offline callers) inject a local downloader via the
+``download_fn`` parameter, so the manifest/SHA logic needs no network.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Optional
+
+from .manifest import (
+    ArtifactFile,
+    ArtifactManifest,
+    ArtifactSpec,
+    default_manifest_path,
+    load_manifest,
+)
+
+DEFAULT_HF_ENDPOINT = "https://huggingface.co"
+
+# A downloader fetches one file from an HF repo into ``dest``.
+# Signature: (repo_id, revision, source_path, dest, endpoint) -> None
+DownloadFn = Callable[[str, str, str, Path, str], None]
+
+
+class ArtifactError(RuntimeError):
+    """Raised when an artifact cannot be resolved, downloaded, or verified."""
+
+
+@dataclass
+class ArtifactInstallResult:
+    """Outcome of :func:`resolve_artifact`."""
+
+    artifact_ref: str
+    install_root: Path
+    installed: list[str] = field(default_factory=list)  # rel paths downloaded
+    skipped: list[str] = field(default_factory=list)  # rel paths already present
+    files: list[Path] = field(default_factory=list)  # absolute installed paths
+
+    @property
+    def ready(self) -> bool:
+        """True when every declared file is present on disk (installed or
+        already-present). ``resolve_artifact`` raises before returning if any
+        file is missing/mismatched, so a returned result is always ready."""
+        return bool(self.files) and not self.missing()
+
+    @property
+    def all_skipped(self) -> bool:
+        """True when nothing needed downloading (every file already present)."""
+        return bool(self.files) and not self.installed
+
+    def missing(self) -> list[str]:  # pragma: no cover - resolve raises first
+        return [str(p) for p in self.files if not p.exists()]
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _hf_download(
+    repo_id: str, revision: str, source_path: str, dest: Path, endpoint: str
+) -> None:
+    """Default downloader backed by ``huggingface_hub.hf_hub_download``.
+
+    Imported lazily so the core package stays installable without the optional
+    ``huggingface_hub`` dependency.
+    """
+    try:
+        from huggingface_hub import hf_hub_download  # type: ignore
+    except ImportError as exc:  # pragma: no cover - exercised only without extra
+        raise ArtifactError(
+            "huggingface_hub is required to download artifacts; install "
+            "voxedge[artifacts] or inject a custom download_fn."
+        ) from exc
+
+    import shutil
+
+    src = hf_hub_download(
+        repo_id=repo_id,
+        filename=source_path,
+        revision=revision or "main",
+        endpoint=endpoint or DEFAULT_HF_ENDPOINT,
+    )
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if Path(src).resolve() != dest.resolve():
+        shutil.copyfile(src, dest)
+
+
+def _resolve_one(
+    spec: ArtifactSpec,
+    item: ArtifactFile,
+    install_root: Path,
+    repo_id: str,
+    revision: str,
+    endpoint: str,
+    download_fn: DownloadFn,
+    result: ArtifactInstallResult,
+) -> None:
+    dest = install_root / item.rel_path
+    result.files.append(dest)
+
+    # Already present and correct → skip.
+    if dest.exists() and _sha256(dest) == item.sha256:
+        result.skipped.append(item.rel_path)
+        return
+
+    if not repo_id:
+        raise ArtifactError(
+            f"artifact {spec.artifact_ref!r} file {item.rel_path!r} is missing "
+            f"and no hf_repo is declared to download it from "
+            f"(preflight fail: required file absent)."
+        )
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        download_fn(repo_id, revision, item.source_rel, dest, endpoint)
+    except ArtifactError:
+        raise
+    except Exception as exc:  # noqa: BLE001 - normalise any downloader failure
+        raise ArtifactError(
+            f"download failed for {spec.artifact_ref!r} file "
+            f"{item.source_rel!r}: {exc}"
+        ) from exc
+
+    if not dest.exists():
+        raise ArtifactError(
+            f"download reported success but file missing: {dest} "
+            f"(artifact {spec.artifact_ref!r})"
+        )
+
+    got = _sha256(dest)
+    if got != item.sha256:
+        dest.unlink(missing_ok=True)
+        raise ArtifactError(
+            f"sha256 mismatch for {item.rel_path!r} in artifact "
+            f"{spec.artifact_ref!r}: got {got}, expected {item.sha256}"
+        )
+    result.installed.append(item.rel_path)
+
+
+def resolve_artifact(
+    artifact_ref: str,
+    install_root: str | Path,
+    *,
+    manifest_path: Optional[str | Path] = None,
+    manifest: Optional[ArtifactManifest] = None,
+    hf_endpoint: str = DEFAULT_HF_ENDPOINT,
+    download_fn: Optional[DownloadFn] = None,
+) -> ArtifactInstallResult:
+    """Resolve, download, SHA-verify and install a named artifact.
+
+    Args:
+        artifact_ref: stable artifact name to resolve in the manifest.
+        install_root: caller-chosen base dir; files land at
+            ``install_root/<file.path>`` (manifest stores relative paths only).
+        manifest_path: path to a JSON manifest. Defaults to the bundled sample
+            manifest when neither ``manifest_path`` nor ``manifest`` is given.
+        manifest: a pre-parsed manifest (takes precedence over ``manifest_path``).
+        hf_endpoint: HF endpoint base URL (env-free; passed by the caller).
+        download_fn: per-file downloader override. Defaults to a
+            ``huggingface_hub``-backed downloader. Tests inject a local one.
+
+    Returns:
+        :class:`ArtifactInstallResult` recording installed/skipped files.
+
+    Raises:
+        ArtifactError: artifact_ref missing, a required file is absent with no
+            repo to fetch it, a download fails, or a SHA-256 mismatch occurs.
+    """
+    if manifest is None:
+        path = manifest_path if manifest_path is not None else default_manifest_path()
+        manifest = load_manifest(path)
+
+    spec = manifest.get(artifact_ref)
+
+    root = Path(install_root)
+    endpoint = (hf_endpoint or manifest.hf_endpoint or DEFAULT_HF_ENDPOINT).rstrip("/")
+    repo_id = spec.hf_repo
+    revision = spec.revision or "main"
+    dl = download_fn or _hf_download
+
+    result = ArtifactInstallResult(artifact_ref=artifact_ref, install_root=root)
+    for item in spec.file_list:
+        _resolve_one(spec, item, root, repo_id, revision, endpoint, dl, result)
+    return result

voxedge/artifacts/manifest.json

@@ -0,0 +1,58 @@
+{
+  "schema_version": 1,
+  "hf_endpoint": "https://huggingface.co",
+  "artifacts": {
+    "rk3588-kokoro-hybrid-2026-05-23": {
+      "artifact_ref": "rk3588-kokoro-hybrid-2026-05-23",
+      "backend_key": "rk.tts",
+      "device": "rk3588",
+      "precision": "int8",
+      "hf_repo": "example-org/example-artifacts",
+      "revision": "main",
+      "sha256": "",
+      "runtime_contract": {
+        "tts_path": "kokoro_hybrid",
+        "closed_loop_validated": true,
+        "env": {
+          "TTS_BACKEND": "kokoro_rknn",
+          "KOKORO_RKNN_MODE": "hybrid",
+          "KOKORO_PREFIX_ONNX": "kokoro-prefix-cpu.onnx",
+          "KOKORO_FRONT_RKNN": "rk3588/kokoro-decoder-front.int8.rknn",
+          "KOKORO_TAIL_ONNX": "kokoro-generator-tail-cpu.onnx"
+        }
+      },
+      "file_list": [
+        {
+          "path": "opt/kokoro-rknn/kokoro-prefix-cpu.onnx",
+          "source_path": "rk3588/kokoro-hybrid-v1/kokoro-prefix-cpu.onnx",
+          "size_bytes": 22922434,
+          "sha256": "549fece07d8696ae9ea60f4667e2680b5ca1f41735af545489a378eed3fe1f1c"
+        },
+        {
+          "path": "opt/kokoro-rknn/kokoro-generator-tail-cpu.onnx",
+          "source_path": "rk3588/kokoro-hybrid-v1/kokoro-generator-tail-cpu.onnx",
+          "size_bytes": 89009749,
+          "sha256": "1bdbb9fdea62922e79fa29891471e7797047f16636bff9bfb8944b28ee451bcb"
+        },
+        {
+          "path": "opt/kokoro-rknn/rk3588/kokoro-decoder-front.int8.rknn",
+          "source_path": "rk3588/kokoro-hybrid-v1/rk3588/kokoro-decoder-front.int8.rknn",
+          "size_bytes": 40599018,
+          "sha256": "a6de7a2512d83a22cfba8e1793b1f463108126dfee4eb8592a28fe7c268d6861"
+        },
+        {
+          "path": "opt/kokoro-rknn/default.npy",
+          "source_path": "rk3588/kokoro-hybrid-v1/default.npy",
+          "size_bytes": 1152,
+          "sha256": "e844b0d3200a28b47a2472d4052c2696ac639197aa0ab06bb3fb708781b5a09d"
+        },
+        {
+          "path": "opt/kokoro-rknn/style.npy",
+          "source_path": "rk3588/kokoro-hybrid-v1/style.npy",
+          "size_bytes": 1152,
+          "sha256": "e844b0d3200a28b47a2472d4052c2696ac639197aa0ab06bb3fb708781b5a09d"
+        }
+      ]
+    }
+  }
+}

voxedge/artifacts/manifest.py

@@ -0,0 +1,209 @@
+"""Backend-agnostic runtime artifact manifest — schema + loader.
+
+This module is **env-free** and **pure-Python** (stdlib + dataclasses only):
+no ``os.environ`` reads, no ``huggingface_hub`` import, no network. It only
+parses and validates a JSON manifest that describes the runtime artifacts a
+backend needs (engines / plugins / model weights / voice-pack sidecars), each
+pinned by SHA-256 and referenced by a stable ``artifact_ref`` name.
+
+Schema (a backend-agnostic generalisation of a per-device artifact manifest):
+
+    {
+      "schema_version": 1,
+      "artifacts": {
+        "<artifact_ref>": {
+          "backend_key": "rk.tts" | "jetson.trt_edge_llm" | ...,
+          "artifact_ref": "<stable name>",         # echoed; must match the key
+          "device":      "rk3588" | "jetson-orin-sm87" | ...,
+          "precision":   "fp16" | "int8" | "w4a16" | ...,
+          "hf_repo":     "<org>/<repo>",
+          "revision":    "main" | "<commit-sha>",
+          "sha256":      "<top-level digest, optional>",
+          "runtime_contract": { ... },             # env/profile constraints
+          "file_list": [
+            { "path": "<artifact-relative path, NO install root>",
+              "source_path": "<HF source path, defaults to path>",
+              "sha256": "<per-file digest>",
+              "size_bytes": <int, optional> },
+            ...
+          ]
+        }
+      }
+    }
+
+``file_list[].path`` is the artifact-relative install path; the install root is
+chosen by the caller (product / profile) at :func:`resolve_artifact` time — the
+manifest never encodes an absolute install root.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+SCHEMA_VERSION = 1
+
+
+class ManifestError(ValueError):
+    """Raised when a manifest is malformed or an artifact_ref is missing."""
+
+
+@dataclass(frozen=True)
+class ArtifactFile:
+    """One file in an artifact's ``file_list``.
+
+    ``path`` is the artifact-relative destination (no install root). ``source_path``
+    is the path inside the HF repo to download from; it defaults to ``path``.
+    """
+
+    path: str
+    sha256: str
+    source_path: str = ""
+    size_bytes: Optional[int] = None
+
+    def __post_init__(self) -> None:
+        if not self.path or not str(self.path).strip():
+            raise ManifestError("file_list entry missing 'path'")
+        if not self.sha256 or not str(self.sha256).strip():
+            raise ManifestError(f"file_list entry {self.path!r} missing 'sha256'")
+        # Normalise source_path to default to path (frozen → object.__setattr__).
+        if not self.source_path:
+            object.__setattr__(self, "source_path", self.path)
+
+    @property
+    def rel_path(self) -> str:
+        """Artifact-relative install path, leading slash stripped."""
+        return self.path.lstrip("/")
+
+    @property
+    def source_rel(self) -> str:
+        """HF-source-relative path, leading slash stripped."""
+        return self.source_path.lstrip("/")
+
+
+@dataclass(frozen=True)
+class ArtifactSpec:
+    """A single named runtime artifact (resolved by ``artifact_ref``)."""
+
+    artifact_ref: str
+    file_list: tuple[ArtifactFile, ...]
+    backend_key: str = ""
+    device: str = ""
+    precision: str = ""
+    hf_repo: str = ""
+    revision: str = "main"
+    sha256: str = ""
+    runtime_contract: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.artifact_ref:
+            raise ManifestError("artifact spec missing 'artifact_ref'")
+        if not self.file_list:
+            raise ManifestError(
+                f"artifact {self.artifact_ref!r} has an empty file_list"
+            )
+
+
+@dataclass(frozen=True)
+class ArtifactManifest:
+    """Parsed, validated manifest. Keyed by ``artifact_ref``."""
+
+    schema_version: int
+    artifacts: dict[str, ArtifactSpec]
+    hf_endpoint: str = ""
+
+    def get(self, artifact_ref: str) -> ArtifactSpec:
+        """Return the :class:`ArtifactSpec` for ``artifact_ref`` or raise."""
+        spec = self.artifacts.get(artifact_ref)
+        if spec is None:
+            raise ManifestError(
+                f"artifact_ref {artifact_ref!r} not found; "
+                f"available={sorted(self.artifacts)}"
+            )
+        return spec
+
+    def __contains__(self, artifact_ref: str) -> bool:
+        return artifact_ref in self.artifacts
+
+
+def _parse_file(raw: dict[str, Any]) -> ArtifactFile:
+    if not isinstance(raw, dict):
+        raise ManifestError(f"file_list entry must be an object, got {type(raw)!r}")
+    return ArtifactFile(
+        path=str(raw.get("path", "")),
+        sha256=str(raw.get("sha256", "")),
+        source_path=str(raw.get("source_path", "") or ""),
+        size_bytes=raw.get("size_bytes"),
+    )
+
+
+def _parse_spec(artifact_ref: str, raw: dict[str, Any]) -> ArtifactSpec:
+    if not isinstance(raw, dict):
+        raise ManifestError(
+            f"artifact {artifact_ref!r} must be an object, got {type(raw)!r}"
+        )
+    declared_ref = str(raw.get("artifact_ref", "") or artifact_ref)
+    if declared_ref != artifact_ref:
+        raise ManifestError(
+            f"artifact key {artifact_ref!r} != declared artifact_ref "
+            f"{declared_ref!r}"
+        )
+    files_raw = raw.get("file_list")
+    if not isinstance(files_raw, list) or not files_raw:
+        raise ManifestError(
+            f"artifact {artifact_ref!r} must declare a non-empty 'file_list'"
+        )
+    file_list = tuple(_parse_file(f) for f in files_raw)
+    return ArtifactSpec(
+        artifact_ref=artifact_ref,
+        file_list=file_list,
+        backend_key=str(raw.get("backend_key", "") or ""),
+        device=str(raw.get("device", "") or ""),
+        precision=str(raw.get("precision", "") or ""),
+        hf_repo=str(raw.get("hf_repo", "") or ""),
+        revision=str(raw.get("revision", "") or "main"),
+        sha256=str(raw.get("sha256", "") or ""),
+        runtime_contract=dict(raw.get("runtime_contract") or {}),
+    )
+
+
+def parse_manifest(data: dict[str, Any]) -> ArtifactManifest:
+    """Validate and parse an in-memory manifest dict."""
+    if not isinstance(data, dict):
+        raise ManifestError(f"manifest must be a JSON object, got {type(data)!r}")
+    schema_version = data.get("schema_version")
+    if schema_version != SCHEMA_VERSION:
+        raise ManifestError(
+            f"unsupported schema_version {schema_version!r} "
+            f"(expected {SCHEMA_VERSION})"
+        )
+    artifacts_raw = data.get("artifacts")
+    if not isinstance(artifacts_raw, dict) or not artifacts_raw:
+        raise ManifestError("manifest must declare a non-empty 'artifacts' map")
+    artifacts = {
+        ref: _parse_spec(ref, spec) for ref, spec in artifacts_raw.items()
+    }
+    return ArtifactManifest(
+        schema_version=schema_version,
+        artifacts=artifacts,
+        hf_endpoint=str(data.get("hf_endpoint", "") or ""),
+    )
+
+
+def load_manifest(manifest_path: str | Path) -> ArtifactManifest:
+    """Load and validate a manifest from a local JSON file path."""
+    path = Path(manifest_path)
+    if not path.exists():
+        raise ManifestError(f"manifest_path not found: {path}")
+    try:
+        data = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ManifestError(f"manifest is not valid JSON: {path}: {exc}") from exc
+    return parse_manifest(data)
+
+
+def default_manifest_path() -> Path:
+    """Path to the sample manifest bundled with the voxedge package."""
+    return Path(__file__).with_name("manifest.json")

voxedge/backends/__init__.py

@@ -0,0 +1,36 @@
+"""voxedge backend ABCs + mock implementations."""
+from __future__ import annotations
+
+from voxedge.backends.base import (
+    ASRBackend,
+    ASRCapability,
+    ASRStream,
+    LLMBackend,
+    LLMEvent,
+    TranscriptionResult,
+    TranslationResult,
+    TranslatorBackend,
+    TranslatorCapability,
+    TranslatorConfig,
+    TTSBackend,
+    TTSCapability,
+    VADBackend,
+    VADSession,
+)
+
+__all__ = [
+    "ASRBackend",
+    "ASRCapability",
+    "ASRStream",
+    "LLMBackend",
+    "LLMEvent",
+    "TranscriptionResult",
+    "TranslationResult",
+    "TranslatorBackend",
+    "TranslatorCapability",
+    "TranslatorConfig",
+    "TTSBackend",
+    "TTSCapability",
+    "VADBackend",
+    "VADSession",
+]

voxedge/backends/_deps.py

@@ -0,0 +1,100 @@
+"""Friendly optional-dependency checks for voxedge backend extras.
+
+The heavy backend adapters (jetson / rk / sherpa) import their native runtime
+packages LAZILY (inside ``__init__`` / ``preload`` / per-call methods) so the
+core stays pip-installable on a CUDA-less, NPU-less dev box (see pyproject
+``[project.optional-dependencies]``). The flip side: when a user selects a
+backend whose extra was never installed, the lazy import previously surfaced as
+a bare, opaque ``ModuleNotFoundError: No module named 'sherpa_onnx'`` — with no
+hint about which extra to install.
+
+This module centralises a single ``require()`` helper that turns a missing
+package into a clear, actionable ``ImportError`` naming both the missing
+distribution and the exact ``pip install voxedge[<extra>]`` incantation. Each
+backend's lazy import site wraps its import in ``require(...)`` (or calls the
+convenience ``_check_*`` helpers) so the failure mode is explicit.
+
+This file imports nothing heavy itself — it is pure stdlib and safe to import
+from the pure-Python core.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Optional
+
+
+def require(
+    module: str,
+    *,
+    extra: str,
+    package: Optional[str] = None,
+):
+    """Import ``module`` or raise a clear, actionable ImportError.
+
+    Parameters
+    ----------
+    module:
+        The importable module name (e.g. ``"sherpa_onnx"``).
+    extra:
+        The voxedge optional-dependency extra that provides it
+        (e.g. ``"sherpa"`` → ``pip install voxedge[sherpa]``).
+    package:
+        The pip distribution name when it differs from ``module``
+        (e.g. module ``cuda`` ships in ``cuda-python``). Used only to make the
+        error message accurate; defaults to ``module``.
+
+    Returns
+    -------
+    The imported module object.
+
+    Raises
+    ------
+    ImportError
+        With a message naming the missing package + the install command.
+    """
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        dist = package or module
+        raise ImportError(
+            f"voxedge[{extra}] requires {dist!r} (module {module!r}), which is "
+            f"not installed. Install the extra with: "
+            f"pip install 'voxedge[{extra}]'"
+        ) from exc
+
+
+def require_all(specs, *, extra: str) -> None:
+    """Check several modules up front; raise on the first that is missing.
+
+    ``specs`` is an iterable of either ``module`` strings or
+    ``(module, package)`` tuples. Use this in a backend ``preload()`` / first
+    use to fail fast with a friendly message before any partial work.
+    """
+    for spec in specs:
+        if isinstance(spec, (tuple, list)):
+            module, package = spec[0], spec[1]
+        else:
+            module, package = spec, None
+        require(module, extra=extra, package=package)
+
+
+# ── convenience wrappers per extra ───────────────────────────────────────────
+
+
+def check_sherpa_deps() -> None:
+    """Fail fast with a friendly error if the ``sherpa`` extra is missing."""
+    require_all([("sherpa_onnx", "sherpa-onnx")], extra="sherpa")
+
+
+def check_rk_deps() -> None:
+    """Fail fast with a friendly error if the ``rk`` extra is missing."""
+    require_all([("rkvoice_stream", "rkvoice-stream")], extra="rk")
+
+
+def check_translator_deps() -> None:
+    """Fail fast with a friendly error if the ``translator`` extra is missing."""
+    require_all(
+        [("ctranslate2", "ctranslate2"), ("sentencepiece", "sentencepiece")],
+        extra="translator",
+    )