From 60e96554dbedb0321bcf8e3d30e19c227f29396d Mon Sep 17 00:00:00 2001 From: Toby Jackson Date: Tue, 17 Nov 2026 19:53:52 +0000 Subject: [PATCH 1/2] Document Windows and macOS installation and inference --- README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f255489..f67185f 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,115 @@ The base installation uses the Akiki engine on supported hosts. ONNX and PyTorch provide compatibility fallbacks for VAD. Install `akiki[onnx]` or `akiki[pytorch]` when you need a compatibility engine. +### Windows and macOS + +The release workflow builds Windows x64, macOS Intel, and macOS Apple Silicon wheels. +Each wheel includes the Akiki engine for VAD and decision models. +Use a Python installation that matches the wheel's architecture. +Windows ARM64 wheels are not available. +The macOS wheels target macOS 11.0 or later. CI tests run on macOS 15. + +The published PyPI 0.2.1 release has no Windows or macOS Akiki engine wheels. +Until the next release, install a verified wheel from the +[Publish workflow](https://github.com/Akiki-AI/akiki-python/actions/workflows/publish.yml). +Select a successful run with completed `build-desktop` jobs. +Get the artifact for your system: + +| System | Workflow artifact | +| --- | --- | +| Windows x64 | `python-distributions-windows-x86_64` | +| macOS Intel | `python-distributions-macos-x86_64` | +| macOS Apple Silicon | `python-distributions-macos-arm64` | + +Extract the artifact into the current directory. +The examples below use the verified 0.2.1 wheel filenames. +The `--force-reinstall` option also replaces an existing portable 0.2.1 installation. +For later releases with these wheels on PyPI, use `pip install --upgrade akiki`. + +#### Windows (PowerShell) + +Use 64-bit x86 Python 3.10 or later. +Run these commands in PowerShell: + +```powershell +py -3 -m venv .venv +.\.venv\Scripts\python.exe -m pip install --force-reinstall ".\akiki-0.2.1-py3-none-win_amd64.whl" +$env:HF_HUB_OFFLINE = "1" +.\.venv\Scripts\python.exe -m akiki vad ".\recording.wav" --engine akiki +.\.venv\Scripts\python.exe -m akiki vad --help +``` + +Use a mono, 16,000 Hz WAV file for `recording.wav`. +To use an existing local MiniLM/BERT classifier, run: + +```powershell +.\.venv\Scripts\python.exe -m akiki minilm --model "C:\models\my-classifier" "Please save my changes." +``` + +Replace `C:\models\my-classifier` with your local export directory. +The `minilm` command gives direct access to the current decision-model runtime. +Use [`DecisionModel`](#decision-models) to manage saved specialists through Python. + +#### macOS (Terminal) + +Use Python 3.10 or later. +Create a virtual environment: + +```bash +python3 -m venv .venv +``` + +For an Apple Silicon Python installation, install the ARM64 wheel: + +```bash +.venv/bin/python -m pip install --force-reinstall ./akiki-0.2.1-py3-none-macosx_11_0_arm64.whl +``` + +For an Intel Python installation, install the x86_64 wheel instead: + +```bash +.venv/bin/python -m pip install --force-reinstall ./akiki-0.2.1-py3-none-macosx_11_0_x86_64.whl +``` + +Run these commands in Terminal: + +```bash +export HF_HUB_OFFLINE=1 +.venv/bin/python -m akiki vad "./recording.wav" --engine akiki +.venv/bin/python -m akiki vad --help +``` + +Use a mono, 16,000 Hz WAV file for `recording.wav`. +To use an existing local MiniLM/BERT classifier, run: + +```bash +.venv/bin/python -m akiki minilm --model "./models/my-classifier" "Please save my changes." +``` + +Replace `./models/my-classifier` with your local export directory. +The Python VAD and decision-model APIs below are the same on all supported systems. + +#### VAD compatibility fallback + +If a native wheel is unavailable, use the ONNX compatibility fallback for VAD. +Create a virtual environment as shown in your platform example above. +On Windows, run: + +```powershell +.\.venv\Scripts\python.exe -m pip install "akiki[onnx]" +.\.venv\Scripts\python.exe -m akiki vad ".\recording.wav" --engine onnx +``` + +On macOS, run: + +```bash +.venv/bin/python -m pip install 'akiki[onnx]' +.venv/bin/python -m akiki vad "./recording.wav" --engine onnx +``` + +This fallback uses the bundled VAD model. It does not enable decision-model inference. +PyTorch is the second VAD compatibility fallback. + ## Python usage Use `akiki.vad` for VAD and `akiki.decision` for decision models. @@ -139,6 +248,7 @@ ONNX and PyTorch are VAD compatibility fallbacks. Linux x86_64 wheels include the Akiki engine for systems with glibc 2.34 or later. Pip and uv select a compatible wheel automatically. No engine build is required. +For Windows and macOS, see the [platform installation examples](#windows-and-macos). Version **0.1.2** includes **Linux ARM64 VAD support**, including Raspberry Pi 5 with a 64-bit OS and glibc 2.28 or later. This wheel includes the Akiki VAD library @@ -672,8 +782,10 @@ between texts. Keep the instance open until all worker calls have finished. longer than `model.max_tokens`. `encode_chunks()` requires complete token sequences and positive finite weights. It adds no special tokens. -MiniLM requires the Akiki engine included in Linux x86_64 and ARM64 wheels; -**ARM64 MiniLM support is experimental**. It has no ONNX or PyTorch alternative. +MiniLM requires the Akiki engine included in native wheels. +These wheels support Linux x86_64 and ARM64, Windows x64, and macOS Intel and Apple Silicon. +See the [Windows and macOS examples](#windows-and-macos) for current wheel availability. +**Linux ARM64 MiniLM support is experimental**. It has no ONNX or PyTorch alternative. It uses up to four CPU threads by default; set `threads` to change this. Projections use `akiki.decision.ModelPrecision.INT8` by default. To use the original weights: From 87f82a813192751fdc6851bd62b20118543232d5 Mon Sep 17 00:00:00 2001 From: Toby Jackson Date: Tue, 17 Nov 2026 19:59:55 +0000 Subject: [PATCH 2/2] Use published package installation in desktop examples --- README.md | 46 +++++++--------------------------------------- 1 file changed, 7 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index f67185f..e119e2a 100644 --- a/README.md +++ b/README.md @@ -38,28 +38,11 @@ Install `akiki[onnx]` or `akiki[pytorch]` when you need a compatibility engine. ### Windows and macOS -The release workflow builds Windows x64, macOS Intel, and macOS Apple Silicon wheels. +Native wheels support Windows x64, macOS Intel, and macOS Apple Silicon. Each wheel includes the Akiki engine for VAD and decision models. -Use a Python installation that matches the wheel's architecture. +Pip selects the wheel for your Python installation. No engine build is required. Windows ARM64 wheels are not available. -The macOS wheels target macOS 11.0 or later. CI tests run on macOS 15. - -The published PyPI 0.2.1 release has no Windows or macOS Akiki engine wheels. -Until the next release, install a verified wheel from the -[Publish workflow](https://github.com/Akiki-AI/akiki-python/actions/workflows/publish.yml). -Select a successful run with completed `build-desktop` jobs. -Get the artifact for your system: - -| System | Workflow artifact | -| --- | --- | -| Windows x64 | `python-distributions-windows-x86_64` | -| macOS Intel | `python-distributions-macos-x86_64` | -| macOS Apple Silicon | `python-distributions-macos-arm64` | - -Extract the artifact into the current directory. -The examples below use the verified 0.2.1 wheel filenames. -The `--force-reinstall` option also replaces an existing portable 0.2.1 installation. -For later releases with these wheels on PyPI, use `pip install --upgrade akiki`. +The macOS wheels target macOS 11.0 or later. #### Windows (PowerShell) @@ -68,7 +51,7 @@ Run these commands in PowerShell: ```powershell py -3 -m venv .venv -.\.venv\Scripts\python.exe -m pip install --force-reinstall ".\akiki-0.2.1-py3-none-win_amd64.whl" +.\.venv\Scripts\python.exe -m pip install akiki $env:HF_HUB_OFFLINE = "1" .\.venv\Scripts\python.exe -m akiki vad ".\recording.wav" --engine akiki .\.venv\Scripts\python.exe -m akiki vad --help @@ -88,27 +71,12 @@ Use [`DecisionModel`](#decision-models) to manage saved specialists through Pyth #### macOS (Terminal) Use Python 3.10 or later. -Create a virtual environment: - -```bash -python3 -m venv .venv -``` - -For an Apple Silicon Python installation, install the ARM64 wheel: - -```bash -.venv/bin/python -m pip install --force-reinstall ./akiki-0.2.1-py3-none-macosx_11_0_arm64.whl -``` - -For an Intel Python installation, install the x86_64 wheel instead: - -```bash -.venv/bin/python -m pip install --force-reinstall ./akiki-0.2.1-py3-none-macosx_11_0_x86_64.whl -``` - +Use a Python installation that matches your Mac's architecture. Run these commands in Terminal: ```bash +python3 -m venv .venv +.venv/bin/python -m pip install akiki export HF_HUB_OFFLINE=1 .venv/bin/python -m akiki vad "./recording.wav" --engine akiki .venv/bin/python -m akiki vad --help