ekko-stt 0.1.0__tar.gz

ekko_stt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emil Schledermann / RyeAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ekko_stt-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: ekko-stt
+Version: 0.1.0
+Summary: Local Danish speech recognition and punctuation with Ekko Tiny and PnC
+Author: Emil Schledermann / RyeAI
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Rye-A1/ekko-danish-stt
+Project-URL: Issues, https://github.com/Rye-A1/ekko-danish-stt/issues
+Keywords: asr,danish,speech-to-text,onnx,gguf
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: filelock<4,>=3.13
+Requires-Dist: huggingface-hub<2,>=0.27
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: soundfile<1,>=0.12
+Requires-Dist: soxr<2,>=0.5
+Provides-Extra: pnc
+Requires-Dist: onnxruntime==1.29.0; extra == "pnc"
+Requires-Dist: tokenizers==0.22.2; extra == "pnc"
+Provides-Extra: tiny-onnx
+Requires-Dist: sherpa-onnx==1.13.6; extra == "tiny-onnx"
+Requires-Dist: sherpa-onnx-core==1.13.6; extra == "tiny-onnx"
+Provides-Extra: local
+Requires-Dist: onnxruntime==1.29.0; extra == "local"
+Requires-Dist: sherpa-onnx==1.13.6; extra == "local"
+Requires-Dist: sherpa-onnx-core==1.13.6; extra == "local"
+Requires-Dist: tokenizers==0.22.2; extra == "local"
+Dynamic: license-file
+
+# Ekko STT
+
+![Ekko STT: Tiny speech recognition and PnC text formatting](https://raw.githubusercontent.com/Rye-A1/ekko-danish-stt/main/assets/ekko-stt-cover.png)
+
+Local inference for [Ekko v1 Tiny](https://huggingface.co/RyeAI/ekko-v1-tiny),
+a Danish speech recognizer with word timestamps, and
+[Ekko PnC](https://huggingface.co/RyeAI/ekko-pnc), its optional punctuation and
+capitalization model. This repository contains the Python runtime and the
+[browser demo](https://huggingface.co/spaces/RyeAI/ekko-tiny-browser).
+
+| Command | Runtime | Default model |
+|---|---|---|
+| `ekko tiny` | parakeet.cpp | Q5_0 GGUF |
+| `ekko tiny-onnx` | sherpa-onnx | int8 ONNX |
+| `ekko pnc` | ONNX Runtime | PnC int8 |
+
+## Run locally
+
+Install [uv](https://docs.astral.sh/uv/), then from this checkout:
+
+```bash
+uv sync --locked --no-editable --extra pnc
+uv run --no-sync ekko tiny audio.wav --pnc --format json
+```
+
+To format an existing transcript without running speech recognition:
+
+```bash
+uv run --no-sync ekko pnc "hej mit navn er emil hvordan går det i dag"
+```
+
+For the ONNX runtime:
+
+```bash
+uv sync --locked --no-editable --extra tiny-onnx --extra pnc
+uv run --no-sync ekko tiny-onnx audio.wav --precision int8 --pnc --format json
+```
+
+The first run downloads model artifacts from Hugging Face and the native
+parakeet.cpp library when needed. Downloads use immutable revisions and
+SHA-256 checks in [the release manifest](https://github.com/Rye-A1/ekko-danish-stt/blob/main/src/ekko/release_manifest.json).
+Set `EKKO_OFFLINE=1` after prefetching to prevent network access.
+
+The [browser demo](https://huggingface.co/spaces/RyeAI/ekko-tiny-browser) runs Tiny and PnC locally
+through WebAssembly. Audio and transcripts stay on the device.
+
+## Development
+
+```bash
+uv sync --locked --extra local
+uv run --no-sync python -m unittest discover -s tests -p 'test_*.py'
+uv build
+```
+
+The source code is MIT licensed. Tiny and PnC weights have their own terms in
+their Hugging Face repositories. See [third-party notices](https://github.com/Rye-A1/ekko-danish-stt/blob/main/THIRD_PARTY_NOTICES.md)
+for runtime dependencies.

ekko_stt-0.1.0/README.md

@@ -0,0 +1,57 @@
+# Ekko STT
+
+![Ekko STT: Tiny speech recognition and PnC text formatting](https://raw.githubusercontent.com/Rye-A1/ekko-danish-stt/main/assets/ekko-stt-cover.png)
+
+Local inference for [Ekko v1 Tiny](https://huggingface.co/RyeAI/ekko-v1-tiny),
+a Danish speech recognizer with word timestamps, and
+[Ekko PnC](https://huggingface.co/RyeAI/ekko-pnc), its optional punctuation and
+capitalization model. This repository contains the Python runtime and the
+[browser demo](https://huggingface.co/spaces/RyeAI/ekko-tiny-browser).
+
+| Command | Runtime | Default model |
+|---|---|---|
+| `ekko tiny` | parakeet.cpp | Q5_0 GGUF |
+| `ekko tiny-onnx` | sherpa-onnx | int8 ONNX |
+| `ekko pnc` | ONNX Runtime | PnC int8 |
+
+## Run locally
+
+Install [uv](https://docs.astral.sh/uv/), then from this checkout:
+
+```bash
+uv sync --locked --no-editable --extra pnc
+uv run --no-sync ekko tiny audio.wav --pnc --format json
+```
+
+To format an existing transcript without running speech recognition:
+
+```bash
+uv run --no-sync ekko pnc "hej mit navn er emil hvordan går det i dag"
+```
+
+For the ONNX runtime:
+
+```bash
+uv sync --locked --no-editable --extra tiny-onnx --extra pnc
+uv run --no-sync ekko tiny-onnx audio.wav --precision int8 --pnc --format json
+```
+
+The first run downloads model artifacts from Hugging Face and the native
+parakeet.cpp library when needed. Downloads use immutable revisions and
+SHA-256 checks in [the release manifest](https://github.com/Rye-A1/ekko-danish-stt/blob/main/src/ekko/release_manifest.json).
+Set `EKKO_OFFLINE=1` after prefetching to prevent network access.
+
+The [browser demo](https://huggingface.co/spaces/RyeAI/ekko-tiny-browser) runs Tiny and PnC locally
+through WebAssembly. Audio and transcripts stay on the device.
+
+## Development
+
+```bash
+uv sync --locked --extra local
+uv run --no-sync python -m unittest discover -s tests -p 'test_*.py'
+uv build
+```
+
+The source code is MIT licensed. Tiny and PnC weights have their own terms in
+their Hugging Face repositories. See [third-party notices](https://github.com/Rye-A1/ekko-danish-stt/blob/main/THIRD_PARTY_NOTICES.md)
+for runtime dependencies.

ekko_stt-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,17 @@
+# Third-party notices
+
+Ekko source code is MIT licensed. It integrates these separately licensed
+projects and artifacts:
+
+- [parakeet.cpp](https://github.com/mudler/parakeet.cpp), MIT. Downloaded native
+  bundles include the upstream license.
+- [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx), Apache-2.0.
+- [ONNX Runtime](https://github.com/microsoft/onnxruntime), MIT.
+- [Hugging Face tokenizers](https://github.com/huggingface/tokenizers), Apache-2.0.
+- [libsndfile](https://github.com/libsndfile/libsndfile), LGPL-2.1-or-later.
+- [libsoxr](https://sourceforge.net/projects/soxr/), LGPL-2.1-or-later.
+
+Model weights have separate terms. See the
+[Tiny model license](https://huggingface.co/RyeAI/ekko-v1-tiny/blob/main/MODEL_LICENSE.md)
+and [PnC model license](https://huggingface.co/RyeAI/ekko-pnc/blob/main/MODEL_LICENSE.md)
+with their bundled notices on Hugging Face.

ekko_stt-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools==84.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ekko-stt"
+version = "0.1.0"
+description = "Local Danish speech recognition and punctuation with Ekko Tiny and PnC"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+authors = [{name = "Emil Schledermann / RyeAI"}]
+keywords = ["asr", "danish", "speech-to-text", "onnx", "gguf"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "filelock>=3.13,<4",
+    "huggingface-hub>=0.27,<2",
+    "numpy>=1.26,<3",
+    "soundfile>=0.12,<1",
+    "soxr>=0.5,<2",
+]
+
+[project.optional-dependencies]
+pnc = ["onnxruntime==1.29.0", "tokenizers==0.22.2"]
+tiny-onnx = ["sherpa-onnx==1.13.6", "sherpa-onnx-core==1.13.6"]
+local = [
+    "onnxruntime==1.29.0",
+    "sherpa-onnx==1.13.6",
+    "sherpa-onnx-core==1.13.6",
+    "tokenizers==0.22.2",
+]
+
+[project.scripts]
+ekko = "ekko.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Rye-A1/ekko-danish-stt"
+Issues = "https://github.com/Rye-A1/ekko-danish-stt/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ekko = ["release_manifest.json"]

ekko_stt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ekko_stt-0.1.0/src/ekko/__init__.py

@@ -0,0 +1,10 @@
+"""Local inference adapters for Ekko v1 Tiny."""
+
+from .artifacts import RELEASE_MANIFEST
+from .pnc import Punctuator
+from .runtime import (EkkoError, TinyBackend, TinyCLIBackend, Transcript, Word, validate_transcript)
+from .tiny_onnx import TinyOnnxBackend
+
+__all__ = ["EkkoError", "Punctuator", "RELEASE_MANIFEST", "TinyBackend",
+           "TinyCLIBackend", "TinyOnnxBackend", "Transcript", "Word",
+           "validate_transcript"]

ekko_stt-0.1.0/src/ekko/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+
+raise SystemExit(main())

ekko_stt-0.1.0/src/ekko/artifacts.py

@@ -0,0 +1,371 @@
+from __future__ import annotations
+
+import hashlib
+import importlib
+import json
+import os
+import platform
+import shutil
+import stat
+import sys
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+
+from filelock import FileLock
+
+from .runtime import EkkoError
+
+
+@dataclass(frozen=True)
+class NativeArtifact:
+    archive: str
+    sha256: str
+    directory: str
+    library: str
+    library_sha256: str
+
+
+@dataclass(frozen=True)
+class HubArtifact:
+    repo_id: str
+    revision: str
+    filename: str
+    sha256: str
+    dialect: str
+
+
+RELEASE_MANIFEST = json.loads(
+    files("ekko").joinpath("release_manifest.json").read_text(encoding="utf-8")
+)
+HUB_ARTIFACTS = {
+    name: HubArtifact(**metadata)
+    for name, metadata in RELEASE_MANIFEST["artifacts"].items()
+}
+HUB_LIBRARY_NAME = RELEASE_MANIFEST["distribution"]
+HUB_LIBRARY_VERSION = RELEASE_MANIFEST["release_version"]
+PARAKEET_VERSION = RELEASE_MANIFEST["native_runtime"]["version"]
+PARAKEET_RELEASE_URL = RELEASE_MANIFEST["native_runtime"]["release_url"]
+_PARAKEET_ARTIFACTS = {
+    tuple(key.split("/", 1)): NativeArtifact(**metadata)
+    for key, metadata in RELEASE_MANIFEST["native_runtime"]["artifacts"].items()
+}
+
+
+def cache_root() -> Path:
+    override = os.environ.get("EKKO_CACHE_DIR")
+    if override:
+        return Path(override).expanduser()
+    current_platform = _platform_name()
+    if current_platform == "darwin":
+        return Path.home() / "Library" / "Caches" / "ekko"
+    if current_platform == "win32":
+        return Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local")) / "ekko"
+    return Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "ekko"
+
+
+def _platform_name() -> str:
+    return sys.platform
+
+
+def _machine(value: str | None = None) -> str:
+    machine = (value or platform.machine()).lower()
+    return {"arm64": "arm64", "aarch64": "aarch64", "amd64": "amd64", "x86_64": "x86_64"}.get(
+        machine, machine
+    )
+
+
+def native_artifact(
+    *,
+    system: str | None = None,
+    machine: str | None = None,
+    libc: tuple[str, str] | None = None,
+) -> NativeArtifact:
+    current_system = system or _platform_name()
+    current_machine = _machine(machine)
+    key = (current_system, current_machine)
+    if key == ("linux", "arm64"):
+        key = ("linux", "aarch64")
+    if key == ("win32", "x86_64"):
+        key = ("win32", "amd64")
+    try:
+        artifact = _PARAKEET_ARTIFACTS[key]
+    except KeyError as error:
+        raise EkkoError(
+            f"no prebuilt parakeet.cpp {PARAKEET_VERSION} library for "
+            f"{current_system}/{current_machine}"
+        ) from error
+    if current_system == "linux":
+        libc_name, libc_version = libc or platform.libc_ver()
+        try:
+            version = tuple(int(part) for part in libc_version.split(".")[:2])
+        except ValueError:
+            version = ()
+        if libc_name.lower() != "glibc" or version < (2, 34):
+            raise EkkoError(
+                "the published parakeet.cpp Linux library requires glibc >= 2.34; "
+                f"detected {libc_name or 'unknown'} {libc_version or 'unknown'}"
+            )
+    return artifact
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _download_verified_hub_file(
+    hub: object,
+    *,
+    repo_id: str,
+    revision: str,
+    filename: str,
+    expected_sha256: str,
+    local_only: bool,
+) -> Path:
+    lock_root = cache_root() / "locks"
+    lock_root.mkdir(parents=True, exist_ok=True)
+    lock = FileLock(str(lock_root / f"hub-{expected_sha256}.lock"))
+
+    def download(*, force: bool) -> Path:
+        try:
+            return Path(
+                hub.hf_hub_download(
+                    repo_id=repo_id,
+                    filename=filename,
+                    revision=revision,
+                    cache_dir=cache_root() / "huggingface",
+                    local_files_only=local_only,
+                    force_download=force,
+                    library_name=HUB_LIBRARY_NAME,
+                    library_version=HUB_LIBRARY_VERSION,
+                )
+            )
+        except Exception as error:
+            raise EkkoError(
+                f"could not download {repo_id}/{filename} at {revision}: {error}"
+            ) from error
+
+    def actual_hash(path: Path) -> str:
+        try:
+            return sha256_file(path)
+        except OSError as error:
+            raise EkkoError(f"could not hash cached artifact {path}: {error}") from error
+
+    with lock:
+        path = download(force=False)
+        actual = actual_hash(path)
+        if actual == expected_sha256:
+            return path
+        if not local_only:
+            path = download(force=True)
+            actual = actual_hash(path)
+            if actual == expected_sha256:
+                return path
+        raise EkkoError(
+            f"checksum mismatch for {repo_id}/{filename}: "
+            f"expected {expected_sha256}, got {actual}; remove the cached file "
+            "and retry"
+        )
+
+
+def _ensure_model_licenses(
+    hub: object, *, repo_id: str, revision: str, local_only: bool
+) -> None:
+    model = next(
+        (
+            metadata
+            for metadata in RELEASE_MANIFEST["models"].values()
+            if metadata["repo_id"] == repo_id
+        ),
+        None,
+    )
+    if model is None:
+        return
+    if model["snapshot_revision"] != revision:
+        raise EkkoError(f"model and legal files use different revisions for {repo_id}")
+    for filename, expected_sha256 in model["license_files"].items():
+        _download_verified_hub_file(
+            hub,
+            repo_id=repo_id,
+            revision=revision,
+            filename=filename,
+            expected_sha256=expected_sha256,
+            local_only=local_only,
+        )
+
+
+def ensure_hub_artifact(name: str, *, offline: bool = False) -> Path:
+    try:
+        artifact = HUB_ARTIFACTS[name]
+    except KeyError as error:
+        raise EkkoError(f"unknown Ekko artifact: {name}") from error
+
+    try:
+        hub = importlib.import_module("huggingface_hub")
+    except ImportError as error:
+        raise EkkoError(
+            "model download requires huggingface-hub; install ekko-stt"
+        ) from error
+
+    local_only = offline or os.environ.get("EKKO_OFFLINE") == "1"
+    path = _download_verified_hub_file(
+        hub,
+        repo_id=artifact.repo_id,
+        revision=artifact.revision,
+        filename=artifact.filename,
+        expected_sha256=artifact.sha256,
+        local_only=local_only,
+    )
+    _ensure_model_licenses(
+        hub,
+        repo_id=artifact.repo_id,
+        revision=artifact.revision,
+        local_only=local_only,
+    )
+    return path
+
+
+def ensure_pnc_directory(*, offline: bool = False) -> Path:
+    paths = [
+        ensure_hub_artifact(name, offline=offline)
+        for name in ("pnc-model", "pnc-tokenizer", "pnc-config")
+    ]
+    parents = {path.parent for path in paths}
+    if len(parents) != 1:
+        raise EkkoError("PnC files did not resolve to one pinned Hub snapshot")
+    return parents.pop()
+
+
+def ensure_tiny_onnx_directory(
+    precision: str, *, offline: bool = False
+) -> Path:
+    if precision not in {"fp32", "int8"}:
+        raise EkkoError(f"unsupported Tiny ONNX precision: {precision}")
+    paths = [
+        ensure_hub_artifact(
+            f"tiny-onnx-{precision}-{component}", offline=offline
+        )
+        for component in ("encoder", "decoder", "joiner")
+    ]
+    paths.append(ensure_hub_artifact("tiny-onnx-tokens", offline=offline))
+    parents = {path.parent for path in paths}
+    if len(parents) != 1:
+        raise EkkoError("Tiny ONNX files did not resolve to one pinned Hub snapshot")
+    return parents.pop()
+
+
+def _safe_target(root: Path, name: str) -> Path:
+    target = (root / name).resolve()
+    if target != root.resolve() and root.resolve() not in target.parents:
+        raise EkkoError(f"unsafe path in native runtime archive: {name}")
+    return target
+
+
+def _extract_archive(archive: Path, destination: Path) -> None:
+    if archive.suffix == ".zip":
+        with zipfile.ZipFile(archive) as bundle:
+            for member in bundle.infolist():
+                _safe_target(destination, member.filename)
+                mode = member.external_attr >> 16
+                if stat.S_ISLNK(mode):
+                    raise EkkoError(
+                        f"links are not allowed in native runtime archive: "
+                        f"{member.filename}"
+                    )
+            bundle.extractall(destination)
+        return
+
+    with tarfile.open(archive, "r:gz") as bundle:
+        for member in bundle.getmembers():
+            _safe_target(destination, member.name)
+            if member.issym() or member.islnk():
+                raise EkkoError(
+                    f"links are not allowed in native runtime archive: {member.name}"
+                )
+        bundle.extractall(destination)
+
+
+def ensure_parakeet_library(*, offline: bool = False) -> Path:
+    override = os.environ.get("EKKO_PARAKEET_LIBRARY")
+    if override:
+        path = Path(override).expanduser()
+        if not path.is_file():
+            raise EkkoError(f"EKKO_PARAKEET_LIBRARY does not exist: {path}")
+        return path
+
+    artifact = native_artifact()
+    install_root = (
+        cache_root()
+        / "native"
+        / f"parakeet-{PARAKEET_VERSION}-{artifact.sha256[:12]}"
+    )
+    library = install_root / artifact.directory / artifact.library
+    install_root.parent.mkdir(parents=True, exist_ok=True)
+    lock = FileLock(str(install_root) + ".lock")
+    with lock:
+        if library.is_file():
+            actual = sha256_file(library)
+            if actual != artifact.library_sha256:
+                raise EkkoError(
+                    f"cached native library checksum mismatch at {library}; "
+                    "remove its versioned cache directory and retry"
+                )
+            return library
+        if offline or os.environ.get("EKKO_OFFLINE") == "1":
+            raise EkkoError(f"parakeet.cpp runtime is not cached at {library}")
+
+        with tempfile.TemporaryDirectory(
+            prefix="parakeet-download-", dir=install_root.parent
+        ) as temporary:
+            temporary_path = Path(temporary)
+            archive = temporary_path / artifact.archive
+            request = urllib.request.Request(
+                f"{PARAKEET_RELEASE_URL}/{artifact.archive}",
+                headers={"User-Agent": "ekko-runtime"},
+            )
+            try:
+                with urllib.request.urlopen(request, timeout=60) as response:
+                    with archive.open("wb") as output:
+                        shutil.copyfileobj(response, output)
+            except OSError as error:
+                raise EkkoError(
+                    f"could not download parakeet.cpp runtime: {error}"
+                ) from error
+            actual = sha256_file(archive)
+            if actual != artifact.sha256:
+                raise EkkoError(
+                    f"parakeet.cpp archive checksum mismatch: expected "
+                    f"{artifact.sha256}, got {actual}"
+                )
+            extracted = temporary_path / "extracted"
+            extracted.mkdir()
+            _extract_archive(archive, extracted)
+            candidate = extracted / artifact.directory / artifact.library
+            if not candidate.is_file():
+                raise EkkoError(f"native runtime archive lacks {artifact.library}")
+            actual_library = sha256_file(candidate)
+            if actual_library != artifact.library_sha256:
+                raise EkkoError(
+                    f"parakeet.cpp library checksum mismatch: expected "
+                    f"{artifact.library_sha256}, got {actual_library}"
+                )
+            try:
+                os.replace(extracted, install_root)
+            except FileExistsError:
+                pass
+
+        if not library.is_file():
+            raise EkkoError(
+                f"native runtime installation failed: {library}"
+            )
+        if sha256_file(library) != artifact.library_sha256:
+            raise EkkoError(f"installed native library checksum mismatch: {library}")
+    return library