From f09f83fe9eed65c117c07fa28097bcd009111f1d Mon Sep 17 00:00:00 2001 From: Toby Jackson Date: Tue, 17 Nov 2026 20:00:48 +0000 Subject: [PATCH] Limit native library discovery to package and explicit paths --- README.md | 14 ++++ docs/releasing.md | 12 ++++ src/akiki/_engines.py | 22 +----- src/akiki/decision.py | 6 +- src/akiki/vad.py | 4 +- tests/test_library_discovery.py | 123 ++++++++++++++++++++++++++++++++ 6 files changed, 157 insertions(+), 24 deletions(-) create mode 100644 tests/test_library_discovery.py diff --git a/README.md b/README.md index f255489..798d8b4 100644 --- a/README.md +++ b/README.md @@ -185,6 +185,20 @@ All VAD engines use the same bundled model and streaming API. The compatibility fallbacks apply to VAD. Decision-model inference currently requires the Akiki engine and a supported export. +Automatic library discovery checks only the package's `native` directory. +It does not search developer directories, Cargo outputs, or the current directory. +For a separately built library, pass `library_path=` in Python or `--library-path` +on the command line. You can also set an engine-specific environment variable: + +| Library | Environment variable | +| --- | --- | +| VAD | `AKIKI_VAD_LIBRARY` | +| Decision models (current MiniLM/BERT runtime) | `AKIKI_MINILM_LIBRARY` | + +An explicit path takes priority over the environment variable and bundled library. +If the selected library is missing or incompatible, no other library is tried. +VAD with `Engine.AUTO` can still use the ONNX, then PyTorch compatibility fallbacks. + ### Model precision `VAD()` and the command line use INT8 by default when running the Akiki engine. diff --git a/docs/releasing.md b/docs/releasing.md index 45961fb..d68deaa 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -114,6 +114,18 @@ requires both on x86_64 and ARM64. Linux wheel architecture is derived from the ELF libraries, so cross-built ARM64 libraries cannot be accidentally labelled as x86_64. +The build helper does not install the libraries into the Python package. +To test a source checkout with these Linux builds, set both runtime paths: + +```bash +export AKIKI_VAD_LIBRARY="$native/libakiki_vad_engine.so" +export AKIKI_MINILM_LIBRARY="$native/libakiki_minilm_engine.so" +``` + +Runtime discovery checks only the package's `native` directory when no path is set. +It does not use `AKIKI_INFERENCE_DIR`, Cargo variables, or developer build directories. +Use the library filenames for your target system with Windows or macOS builds. + ## Build the Linux ARM64 wheel The wheel includes VAD and the current MiniLM/BERT decision runtime. diff --git a/src/akiki/_engines.py b/src/akiki/_engines.py index 662b7dd..2be8aef 100644 --- a/src/akiki/_engines.py +++ b/src/akiki/_engines.py @@ -141,30 +141,12 @@ def library_name(stem="akiki_vad_engine"): def library_candidates(library_path=None, stem="akiki_vad_engine", variable="AKIKI_VAD_LIBRARY"): + """Use an explicit library or the library in the package.""" explicit = library_path or os.environ.get(variable) if explicit: yield Path(explicit).expanduser() return - name = library_name(stem) - yield Path(__file__).parent / "native" / name - # The offline build helper keeps artifacts inside the Python workspace. - source_root = Path(__file__).resolve().parents[2] - yield source_root / ".cache/native-target/release" / name - target_dir = os.environ.get("CARGO_TARGET_DIR") - roots = [ - Path.home() / "projects/Akiki/akiki-inference", - Path("/projects/Akiki/akiki-inference"), - ] - if os.environ.get("AKIKI_INFERENCE_DIR"): - roots.insert(0, Path(os.environ["AKIKI_INFERENCE_DIR"]).expanduser()) - targets = ([Path(target_dir).expanduser()] if target_dir else []) + [ - r / "target" for r in roots - ] - for target in targets: - if os.environ.get("CARGO_BUILD_TARGET"): - target = target / os.environ["CARGO_BUILD_TARGET"] - for profile in ("release", "debug"): - yield target / profile / name + yield Path(__file__).resolve().parent / "native" / library_name(stem) class AkikiBackend(Backend): diff --git a/src/akiki/decision.py b/src/akiki/decision.py index 33a880a..966bc89 100644 --- a/src/akiki/decision.py +++ b/src/akiki/decision.py @@ -307,7 +307,8 @@ def __init__( available CPUs when loading each specialist. ``model_precision`` requires this module's enum and defaults to ``ModelPrecision.INT8``. ``library_path`` selects an existing native MiniLM shared library. - It overrides ``AKIKI_MINILM_LIBRARY`` and automatic library discovery. + It overrides ``AKIKI_MINILM_LIBRARY`` and the bundled library. + Automatic discovery does not search developer directories. Native loading occurs on the first inference or tokenization call. Use a context manager or ``close()`` to release the loaded models. @@ -774,7 +775,8 @@ def __init__( Passing ``None`` keeps the variant's configured chunk length. library_path : str or os.PathLike, optional Path to a specific Akiki MiniLM shared library. Overrides - ``AKIKI_MINILM_LIBRARY`` and automatic discovery. + ``AKIKI_MINILM_LIBRARY`` and the bundled library. + Automatic discovery does not search developer directories. Raises ------ diff --git a/src/akiki/vad.py b/src/akiki/vad.py index 0ad0b97..9bbc145 100644 --- a/src/akiki/vad.py +++ b/src/akiki/vad.py @@ -176,8 +176,8 @@ def __init__( Pass an ``Engine`` member, such as ``Engine.AKIKI``. library_path : str or pathlib.Path, optional Specific local Akiki shared library to load. Affects only the Akiki - engine. If omitted, use ``AKIKI_VAD_LIBRARY`` or discover a bundled - or locally built library. + engine. If omitted, use ``AKIKI_VAD_LIBRARY`` or the bundled library. + Automatic discovery does not search developer directories. model_precision : ModelPrecision, optional One of ``ModelPrecision.FP32``, ``FP16``, ``BF16``, ``INT8``, ``INT4``, or ``INT8_FP32_INPUT``. If omitted, Akiki uses INT8 and diff --git a/tests/test_library_discovery.py b/tests/test_library_discovery.py new file mode 100644 index 0000000..4a757c7 --- /dev/null +++ b/tests/test_library_discovery.py @@ -0,0 +1,123 @@ +"""Load native engines from the package or an explicit local path.""" + +from pathlib import Path + +import pytest + +from akiki import _engines, decision +from akiki.vad import VAD, Engine, ModelPrecision + + +@pytest.fixture(params=["win32", "darwin", "linux"]) +def native_library(request, tmp_path, monkeypatch): + monkeypatch.setattr(_engines.sys, "platform", request.param) + monkeypatch.setattr(_engines, "__file__", str(tmp_path / "site-packages/akiki/_engines.py")) + for variable in ("AKIKI_VAD_LIBRARY", "AKIKI_MINILM_LIBRARY"): + monkeypatch.delenv(variable, raising=False) + home = tmp_path / "home" + monkeypatch.setenv("HOME", str(home)) + monkeypatch.setenv("USERPROFILE", str(home)) + monkeypatch.setenv("AKIKI_INFERENCE_DIR", str(tmp_path / "inference")) + monkeypatch.setenv("CARGO_TARGET_DIR", str(tmp_path / "cargo")) + monkeypatch.setenv("CARGO_BUILD_TARGET", "target-triple") + monkeypatch.chdir(tmp_path) + return (tmp_path / "site-packages/akiki/native").resolve() + + +@pytest.fixture( + params=[ + ("akiki_vad_engine", "AKIKI_VAD_LIBRARY"), + ("akiki_minilm_engine", "AKIKI_MINILM_LIBRARY"), + ] +) +def engine_library(request, native_library, tmp_path): + stem, variable = request.param + name = _engines.library_name(stem) + # Existing developer outputs must not become runtime candidates. + for directory in ( + tmp_path, + tmp_path / ".cache/native-target/release", + tmp_path / "home/projects/Akiki/akiki-inference/target/target-triple/release", + tmp_path / "inference/target/target-triple/release", + tmp_path / "cargo/target-triple/release", + tmp_path / "cargo/target-triple/debug", + ): + directory.mkdir(parents=True, exist_ok=True) + (directory / name).write_bytes(b"developer library") + return stem, variable, native_library / name + + +def test_automatic_search_checks_only_the_package(engine_library): + stem, variable, bundled = engine_library + assert list(_engines.library_candidates(stem=stem, variable=variable)) == [bundled] + + +def test_explicit_path_precedes_environment_and_package(engine_library, tmp_path, monkeypatch): + stem, variable, bundled = engine_library + environment = tmp_path / "environment library" / bundled.name + monkeypatch.setenv(variable, str(environment)) + assert list(_engines.library_candidates(stem=stem, variable=variable)) == [environment] + + explicit = tmp_path / "explicit library" / bundled.name + for path in (explicit, str(explicit)): + assert list(_engines.library_candidates(path, stem, variable)) == [explicit] + + home_library = Path.home() / "local library" / bundled.name + relative = Path("~/local library") / bundled.name + assert list(_engines.library_candidates(relative, stem, variable)) == [home_library] + monkeypatch.setenv(variable, str(relative)) + assert list(_engines.library_candidates(stem=stem, variable=variable)) == [home_library] + + +def load_engine(stem, library_path=None): + if stem == "akiki_vad_engine": + return VAD( + engine=Engine.AKIKI, + model_precision=ModelPrecision.FP32, + library_path=library_path, + ) + return decision._load_library(library_path) + + +@pytest.mark.parametrize("present", [False, True]) +def test_consumers_do_not_load_developer_libraries(engine_library, monkeypatch, present): + stem, variable, bundled = engine_library + if present: + bundled.parent.mkdir(parents=True) + bundled.write_bytes(b"incompatible bundled library") + attempts = [] + + def load(path): + attempts.append(Path(path)) + raise OSError("incompatible library") + + monkeypatch.setattr(_engines.ctypes, "CDLL", load) + with pytest.raises(RuntimeError, match="No compatible Akiki"): + load_engine(stem) + assert attempts == ([bundled] if present else []) + + +@pytest.mark.parametrize("present", [False, True]) +def test_failed_override_does_not_load_another_library( + engine_library, tmp_path, monkeypatch, present +): + stem, variable, bundled = engine_library + bundled.parent.mkdir(parents=True) + bundled.write_bytes(b"bundled library") + explicit = tmp_path / "custom" / bundled.name + if present: + explicit.parent.mkdir() + explicit.write_bytes(b"incompatible explicit library") + attempts = [] + + def load(path): + attempts.append(Path(path)) + raise OSError("incompatible library") + + monkeypatch.setattr(_engines.ctypes, "CDLL", load) + for library_path in (explicit, None): + attempts.clear() + monkeypatch.setenv(variable, str(explicit if library_path is None else bundled)) + with pytest.raises(RuntimeError, match=variable): + load_engine(stem, library_path) + assert attempts == ([explicit.resolve()] if present else [])