> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Edge workflow dependencies
> Python packages and SDK extras for voice pipelines — compile server, edge worker, and catalog STT models
Edge voice workflows use **three layers** of dependencies. Each layer must be satisfied or compile/sync fails with an actionable error (for example: *"… is not installed on the compile server"*).
| Layer | Where | Purpose |
| ------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------- |
| **1. Compile server** | Django / `cyberwave-backend` | Validates imports and (for Wake Word) downloads weights **before** shipping `wf_*.py` |
| **2. Edge worker image** | `cyberwaveos/edge-ml-worker` | Runs generated Python; install matching `cyberwave[...]` extras |
| **3. Catalog / emitters** | `edge-sync` → `model_requirements` | Tells operators which **one** SDK extra to install per node or STT model |
**Do not install `ml-all` on Raspberry Pi** unless you need every vision + STT + VAD runtime in one image. Catalog entries declare **one minimal extra** each (`ml-stt`, `ml-stt-faster`, …). Use `ml-all` only for CI/dev fat images.
***
## Workflow nodes
| Node | Compile server (`base.txt`) | Edge SDK extra | `model_requirements` |
| -------------------------------------------------------------------------- | -------------------------------------- | ----------------------------------------------- | --------------------------- |
| [Audio Track](/feature-reference/workflows/audio-track/overview) | — (no ML import) | `zenoh` on worker; `microphone` on capture host | — |
| [Audio Assistant](/feature-reference/workflows/audio-assistant/overview) | `silero-vad` (+ torch transitive) | `ml-audio` | `edge_package: ml-audio` |
| [Wake Word Engine](/feature-reference/workflows/wake-word-engine/overview) | `openwakeword`, `onnxruntime` | `ml-wakeword` | `edge_package: ml-wakeword` |
| [Call Model — STT](/feature-reference/workflows/call-model-stt-edge) | `pywhispercpp` and/or `faster-whisper` | From catalog metadata | Per selected ML model |
| [Fuzzy Matcher](/feature-reference/workflows/fuzzy-matcher) | `rapidfuzz` | `fuzzy-match` | `edge_package: fuzzy-match` |
| [Twin](/feature-reference/workflows/twin) | `httpx` (base) | Base `cyberwave` | — |
| [Virtual Controller](/feature-reference/workflows/virtual-controller) | `paho-mqtt` (base) | Base `cyberwave` | — |
Compile checks mirror the [Wake Word](/feature-reference/workflows/wake-word-engine/models-and-compile) pattern: `WorkflowCodeAssembler` calls `provision_*_for_compile()` before emitting edge worker source.
***
## SDK extras (`cyberwave-python`)
Defined in `cyberwave-sdks/cyberwave-python/pyproject.toml`. Install on edge with `pip install 'cyberwave[]'` or `pip install 'cyberwave-edge-core[]'` (thin passthrough).
| Extra | Packages | Used by |
| --------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `ml-audio` | `silero-vad` | Audio Assistant |
| `ml-wakeword` | `openwakeword`, `onnxruntime` | Wake Word Engine |
| `ml-stt` | `pywhispercpp` | Call Model — Whisper.cpp catalog models |
| `ml-stt-faster` | `faster-whisper` | Call Model — Faster Whisper catalog models |
| `fuzzy-match` | `rapidfuzz` | Fuzzy Matcher |
| `zenoh` | `eclipse-zenoh` | Audio Track worker hook |
| `microphone` | `sounddevice`, `av`, … | Host mic capture (driver side) |
| `ml-all` | `ml-all-vision` + `ml-all-audio` (includes `torchaudio`) | **CI/dev only** |
| `ml-all-audio` | `openwakeword`, `onnxruntime`, `pywhispercpp`, `faster-whisper`, `silero-vad`, `torchaudio`, `rapidfuzz` | Fat audio image (avoid on Pi) |
| `ml-all-vision` | `ultralytics`, `onnxruntime`, `opencv-python`, `tflite-runtime` | Vision-only fat image |
***
## Catalog STT models (`edge_package`)
Each public STT catalog entry sets `metadata.edge_package` to **one** extra (never `ml-all`).
| Catalog model | `edge_runtime` | `edge_package` | Weight path (`edge_model_path`) |
| ------------------------------- | ---------------- | --------------- | ---------------------------------------- |
| Whisper Tiny EN Q5\_1 | `whisper_cpp` | `ml-stt` | `models/whisper/ggml-tiny.en-q5_1.bin` |
| Whisper Base EN Q5\_1 | `whisper_cpp` | `ml-stt` | `models/whisper/ggml-base.en-q5_1.bin` |
| Whisper Small EN Q5\_1 | `whisper_cpp` | `ml-stt` | `models/whisper/ggml-small.en-q5_1.bin` |
| Whisper Tiny Multilingual Q5\_1 | `whisper_cpp` | `ml-stt` | `models/whisper/ggml-tiny-q5_1.bin` |
| Whisper Base Multilingual Q5\_1 | `whisper_cpp` | `ml-stt` | `models/whisper/ggml-base-q5_1.bin` |
| Faster Whisper Tiny EN | `faster_whisper` | `ml-stt-faster` | `models/whisper/faster-whisper-tiny.en` |
| Faster Whisper Base EN | `faster_whisper` | `ml-stt-faster` | `models/whisper/faster-whisper-base.en` |
| Faster Whisper Small EN | `faster_whisper` | `ml-stt-faster` | `models/whisper/faster-whisper-small.en` |
Faster Whisper also sets `faster_whisper_model_id` (`tiny.en`, `base.en`, `small.en`) for CTranslate2. Hybrid models may fall back to the cloud whisper node when not running on edge.
See [Call Model STT on edge](/feature-reference/workflows/call-model-stt-edge).
***
## Compile server setup (Django)
Packages are listed in `cyberwave-backend/requirements/base.txt`:
```text theme={null}
openwakeword>=0.6.0
onnxruntime>=1.16.0
rapidfuzz>=3.0.0
silero-vad>=6.0
pywhispercpp==1.4.1
faster-whisper>=1.1.1
```
After changing `base.txt`, **rebuild the Django Docker image**:
```bash theme={null}
cd cyberwave-backend
docker compose -f local.yml build django
docker compose -f local.yml up -d django
```
Without rebuild, compile fails with errors like:
* *"Wake Word Engine but openwakeword is not installed on the compile server"*
* *"Fuzzy Matcher but rapidfuzz is not installed …"*
* *"Audio Assistant but silero-vad (or torch) is not installed …"*
* *"whisper.cpp but pywhispercpp is not installed …"*
* *"faster-whisper is not installed …"*
***
## Edge worker image
Default `cyberwaveos/edge-ml-worker` installs a **fat** extra set for dev:
`ml,ml-onnx,ml-stt,ml-stt-faster,ml-audio,fuzzy-match,zenoh,image,schedule` plus `openwakeword` via `--no-deps` (Python 3.12).
For **Raspberry Pi**, rebuild a slim image with only what your workflow uses:
```bash theme={null}
# whisper.cpp Tiny + VAD + wake word + fuzzy (no faster-whisper, no YOLO)
docker build \
--build-arg CYBERWAVE_SDK_EXTRAS=ml-stt,ml-audio,fuzzy-match,zenoh,schedule \
-f cyberwave-edge-runtime/runtime-services/workers/edge-ml-worker/Dockerfile .
```
```bash theme={null}
# Faster Whisper STT only
docker build \
--build-arg CYBERWAVE_SDK_EXTRAS=ml-stt-faster,ml-audio,zenoh,schedule \
-f cyberwave-edge-runtime/runtime-services/workers/edge-ml-worker/Dockerfile .
```
***
## Typical voice pipeline (extras needed)
```
audio_track → zenoh (+ microphone on capture host)
→ audio_assistant → ml-audio
→ wake_word_engine → ml-wakeword
→ call_model (STT) → ml-stt OR ml-stt-faster (per catalog model)
→ fuzzy_matcher → fuzzy-match
twin → base cyberwave
virtual_controller → base cyberwave
```
Install the **union** of extras used in your graph — not `ml-all`.
***
## Related
PCM format and pipeline overview
Whisper.cpp vs Faster Whisper on edge
Compile-time model download
Weight download on device