feat(voice): open-vocabulary wake phrases via sherpa-onnx KWS

New "sherpa" wake_word provider: the configured phrase is BPE-tokenized at runtime against a small streaming zipformer KWS model (~13 MB English, one-time download cached under HERMES_HOME), so ANY typed phrase works with zero training — including per-profile phrases like "hey coder". wake.sherpa lazy-dep group + [wake] extra grow sherpa-onnx/sentencepiece; requirements probe routes per provider; sensitivity maps onto sherpa keywords_threshold. E2E-verified on real audio (target phrase fires, foreign phrase stays silent, reset drops buffered state).
2026-07-29 18:46:59 +00:00 · 2026-07-24 08:39:19 -07:00 · 2026-07-24 08:39:19 -07:00 · 0ae305ed4e
commit 0ae305ed4e
parent dcc26fa28a
7 changed files with 371 additions and 13 deletions
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@ -2380,8 +2380,8 @@ DEFAULT_CONFIG = {
    "wake_word": {
        "enabled": False,
        "surface": "auto",            # eligible surface: "auto" (first claimant) | "cli" | "tui" | "gui"
-        "provider": "openwakeword",   # "openwakeword" (free, local) | "porcupine" (premium; needs PORCUPINE_ACCESS_KEY)
-        "phrase": "hey hermes",       # cosmetic label only; detection is keyed by the engine model/keyword below
+        "provider": "openwakeword",   # "openwakeword" (free, local) | "sherpa" (free, ANY phrase, no training) | "porcupine" (premium; needs PORCUPINE_ACCESS_KEY)
+        "phrase": "hey hermes",       # for "sherpa" this IS the detected phrase (any text works); for other engines it's a cosmetic label — detection is keyed by the model/keyword below
        "sensitivity": 0.5,           # 0.0-1.0 detection threshold (higher = stricter)
        "start_new_session": True,    # start a fresh session on wake vs. continue the current one
        "openwakeword": {
@ -2392,6 +2392,11 @@ DEFAULT_CONFIG = {
            "model": "hey_hermes",
            "inference_framework": "onnx",  # "onnx" | "tflite"
        },
+        "sherpa": {
+            # Optional path to a sherpa-onnx KWS model directory. Empty =
+            # auto-download the small English zipformer model on first use.
+            "model_dir": "",
+        },
        "porcupine": {
            # Built-in keyword ("jarvis", "computer", "bumblebee", ...) or a path
            # to a custom .ppn from the Picovoice Console.
--- a/pyproject.toml
+++ b/pyproject.toml
@ -175,12 +175,16 @@ voice = [
  "sounddevice==0.5.5",
  "numpy==2.4.3",
 ]
-# "Hey Hermes" wake word — on-device hotword detection. Both engines are
-# optional; openWakeWord (ONNX) is the free default, Porcupine the premium
-# alternative. Lazy-installed on first /wake; mirrored in tools/lazy_deps.py.
+# "Hey Hermes" wake word — on-device hotword detection. All engines are
+# optional; openWakeWord (ONNX) is the free default, sherpa-onnx adds
+# open-vocabulary phrases (any typed phrase, zero training), Porcupine is
+# the premium alternative. Lazy-installed on first /wake; mirrored in
+# tools/lazy_deps.py.
 wake = [
  "openwakeword==0.6.0",
  "onnxruntime==1.27.0",
+  "sherpa-onnx==1.13.4",
+  "sentencepiece==0.2.2",
  "pvporcupine==4.0.3",
  "sounddevice==0.5.5",
  "numpy==2.4.3",
--- a/tests/tools/test_wake_word.py
+++ b/tests/tools/test_wake_word.py
@ -194,6 +194,114 @@ def test_openwakeword_bundled_model_matches_framework(monkeypatch):
    assert downloaded[0].endswith(".tflite")


+# ── sherpa-onnx open-vocabulary engine ───────────────────────────────────
+
+
+def _install_fake_sherpa(monkeypatch, tmp_path):
+    """Fake sherpa_onnx + a fake model dir so the engine builds offline."""
+    calls = {"text2token": [], "spotter": [], "results": []}
+
+    model_dir = tmp_path / "kws-model"
+    model_dir.mkdir()
+    for name in (
+        "tokens.txt",
+        "bpe.model",
+        "encoder-epoch-12-avg-2-chunk-16-left-64.onnx",
+        "decoder-epoch-12-avg-2-chunk-16-left-64.onnx",
+        "joiner-epoch-12-avg-2-chunk-16-left-64.onnx",
+    ):
+        (model_dir / name).write_bytes(b"x")
+
+    class _FakeStream:
+        def accept_waveform(self, sample_rate, samples):
+            pass
+
+    class _FakeSpotter:
+        def __init__(self, **kwargs):
+            calls["spotter"].append(kwargs)
+
+        def create_stream(self):
+            return _FakeStream()
+
+        def is_ready(self, stream):
+            return bool(calls["results"])
+
+        def decode_stream(self, stream):
+            pass
+
+        def get_result(self, stream):
+            return calls["results"].pop(0) if calls["results"] else ""
+
+        def reset_stream(self, stream):
+            pass
+
+    def _fake_text2token(phrases, tokens, tokens_type, bpe_model):
+        calls["text2token"].append(list(phrases))
+        return [p.split() for p in phrases]
+
+    sherpa = types.ModuleType("sherpa_onnx")
+    sherpa.KeywordSpotter = _FakeSpotter
+    sherpa.text2token = _fake_text2token
+    monkeypatch.setitem(sys.modules, "sherpa_onnx", sherpa)
+    monkeypatch.setattr("tools.lazy_deps.ensure", lambda *a, **k: None)
+    return calls, model_dir
+
+
+def test_sherpa_engine_tokenizes_configured_phrase_at_runtime(monkeypatch, tmp_path):
+    # The open-vocab core: the phrase from config is tokenized at runtime —
+    # no per-phrase model, no training artifact.
+    calls, model_dir = _install_fake_sherpa(monkeypatch, tmp_path)
+    eng = ww._SherpaKwsEngine({
+        "provider": "sherpa",
+        "phrase": "purple monkey dishwasher",
+        "sherpa": {"model_dir": str(model_dir)},
+    })
+    assert calls["text2token"] == [["PURPLE MONKEY DISHWASHER"]]
+    # keywords file was materialized with an underscored display name
+    with open(eng._keywords_file) as f:
+        line = f.read().strip()
+    assert line.endswith("@PURPLE_MONKEY_DISHWASHER")
+    eng.close()
+    assert not os.path.exists(eng._keywords_file)
+
+
+def test_sherpa_engine_process_fires_and_resets(monkeypatch, tmp_path):
+    calls, model_dir = _install_fake_sherpa(monkeypatch, tmp_path)
+    eng = ww._SherpaKwsEngine({
+        "provider": "sherpa", "phrase": "hey hermes",
+        "sherpa": {"model_dir": str(model_dir)},
+    })
+    frame = [0] * eng.frame_length
+    assert eng.process(frame) is False       # no result queued
+    calls["results"].append("HEY_HERMES")
+    assert eng.process(frame) is True        # queued result → fire
+    old_stream = eng._stream
+    eng.reset()
+    assert eng._stream is not old_stream     # fresh decoder state
+
+
+def test_sherpa_provider_routing(monkeypatch, tmp_path):
+    calls, model_dir = _install_fake_sherpa(monkeypatch, tmp_path)
+    for alias in ("sherpa", "sherpa-onnx", "kws", "open"):
+        eng = ww._build_engine({
+            "provider": alias, "phrase": "x",
+            "sherpa": {"model_dir": str(model_dir)},
+        })
+        assert isinstance(eng, ww._SherpaKwsEngine)
+
+
+def test_sherpa_requirements_probe_uses_sherpa_feature(monkeypatch):
+    seen = {}
+    monkeypatch.setattr(ww, "_audio_available", lambda: True)
+    monkeypatch.setattr(
+        "tools.lazy_deps.is_available", lambda f: seen.setdefault("feature", f) or True
+    )
+    r = ww.check_wake_word_requirements({"provider": "sherpa", "phrase": "anything at all"})
+    assert seen["feature"] == "wake.sherpa"
+    assert r["provider"] == "sherpa"
+    assert r["phrase"] == "anything at all"
+
+
 # ── Detector loop ────────────────────────────────────────────────────────


--- a/tools/lazy_deps.py
+++ b/tools/lazy_deps.py
@ -146,6 +146,15 @@ LAZY_DEPS: dict[str, tuple[str, ...]] = {
        "sounddevice==0.5.5",
        "numpy==2.4.3",
    ),
+    # Open-vocabulary keyword spotting: any typed phrase, zero training.
+    # sentencepiece is required by sherpa_onnx.text2token (runtime phrase
+    # tokenization) even though sherpa-onnx doesn't declare it.
+    "wake.sherpa": (
+        "sherpa-onnx==1.13.4",
+        "sentencepiece==0.2.2",
+        "sounddevice==0.5.5",
+        "numpy==2.4.3",
+    ),
    "wake.porcupine": (
        "pvporcupine==4.0.3",
        "sounddevice==0.5.5",
--- a/tools/wake_word.py
+++ b/tools/wake_word.py
@ -6,12 +6,16 @@ desktop GUI (one of them owns it, gated by ``wake_surface_enabled``): say the
 wake word, Hermes opens a fresh session and captures voice via the existing
 pipeline, then answers.

-Two engines, both fully on-device (no audio leaves the machine for detection):
+Three engines, all fully on-device (no audio leaves the machine for detection):

 * **openwakeword** (default, free, no API key) — loads an ONNX model. Defaults
  to the bundled "hey hermes" model (``tools/wakewords/``) so the wake word
  works out of the box; or point ``wake_word.openwakeword.model`` at a built-in
  name (``hey_jarvis``, ``alexa``, …) or a custom ``.onnx`` for another phrase.
+* **sherpa** (free, no API key, open vocabulary) — sherpa-onnx keyword
+  spotting. Detects ANY typed phrase with no training: set
+  ``wake_word.phrase`` and the phrase is tokenized at runtime against a small
+  streaming zipformer model (~13 MB English model, one-time download).
 * **porcupine** (premium) — Picovoice's engine. Needs ``PORCUPINE_ACCESS_KEY``;
  supports built-in keywords and custom ``.ppn`` files from the Picovoice
  Console.
@ -224,6 +228,139 @@ class _OpenWakeWordEngine(_Engine):
        self.reset()


+# sherpa-onnx open-vocabulary KWS model: a small streaming zipformer
+# transducer. English (GigaSpeech); one-time download, cached under
+# HERMES_HOME. Keywords are typed phrases tokenized at RUNTIME — no
+# training step, unlike openWakeWord/Porcupine custom models.
+_SHERPA_KWS_MODEL_URL = (
+    "https://github.com/k2-fsa/sherpa-onnx/releases/download/kws-models/"
+    "sherpa-onnx-kws-zipformer-gigaspeech-3.3M-2024-01-01.tar.bz2"
+)
+_SHERPA_KWS_MODEL_DIR = "sherpa-onnx-kws-zipformer-gigaspeech-3.3M-2024-01-01"
+
+
+def _sherpa_model_root() -> Path:
+    from hermes_constants import get_hermes_home
+
+    return get_hermes_home() / "cache" / "wakewords"
+
+
+def _ensure_sherpa_model(root: Optional[Path] = None) -> Path:
+    """Download + unpack the sherpa KWS model once; return its directory."""
+    root = root or _sherpa_model_root()
+    target = root / _SHERPA_KWS_MODEL_DIR
+    if (target / "tokens.txt").exists():
+        return target
+    import tarfile
+    import urllib.request
+
+    root.mkdir(parents=True, exist_ok=True)
+    archive = root / f"{_SHERPA_KWS_MODEL_DIR}.tar.bz2"
+    logger.info("wake word: downloading sherpa KWS model (one-time, ~13 MB)")
+    urllib.request.urlretrieve(_SHERPA_KWS_MODEL_URL, archive)  # noqa: S310
+    with tarfile.open(archive, "r:bz2") as tf:
+        tf.extractall(root, filter="data")
+    archive.unlink(missing_ok=True)
+    if not (target / "tokens.txt").exists():
+        raise RuntimeError(f"sherpa KWS model unpack failed: {target}")
+    return target
+
+
+class _SherpaKwsEngine(_Engine):
+    """sherpa-onnx open-vocabulary keyword spotting — any typed phrase, zero training.
+
+    The configured ``wake_word.phrase`` is BPE-tokenized at runtime against the
+    model's vocabulary, so "hey hermes", "hey coder", or any other phrase works
+    immediately. Here ``phrase`` is DETECTION config, not a cosmetic label.
+    """
+
+    # sherpa's streaming zipformer consumes arbitrary chunk sizes; 1280
+    # samples (80 ms) matches the shared capture path.
+    frame_length = 1280
+
+    def __init__(self, cfg: Dict[str, Any]):
+        from tools import lazy_deps
+
+        lazy_deps.ensure("wake.sherpa", prompt=False)
+
+        import sherpa_onnx
+        from sherpa_onnx import text2token
+
+        sub = cfg.get("sherpa") if isinstance(cfg.get("sherpa"), dict) else {}
+        model_dir = str(sub.get("model_dir") or "").strip()
+        d = Path(model_dir) if model_dir else _ensure_sherpa_model()
+        if not (d / "tokens.txt").exists():
+            raise RuntimeError(f"sherpa KWS model not found at {d}")
+
+        phrase = str(_get(cfg, "phrase") or "hey hermes").strip()
+        # Runtime tokenization of the arbitrary phrase — the open-vocab core.
+        # sherpa keyword entries reject spaces in the @display-name; underscore it.
+        tokens = text2token(
+            [phrase.upper()],
+            tokens=str(d / "tokens.txt"),
+            tokens_type="bpe",
+            bpe_model=str(d / "bpe.model"),
+        )
+        import tempfile
+
+        kw = tempfile.NamedTemporaryFile(
+            mode="w", suffix=".txt", prefix="hermes-kws-", delete=False
+        )
+        display = phrase.upper().replace(" ", "_")
+        kw.write(" ".join(tokens[0]) + f" @{display}\n")
+        kw.close()
+        self._keywords_file = kw.name
+
+        # Map the shared 0..1 sensitivity onto sherpa's keywords_threshold
+        # (posterior probability; its default is 0.25).
+        threshold = 0.1 + 0.5 * _sensitivity(cfg)
+
+        def _model_file(pattern: str) -> str:
+            hits = sorted(d.glob(pattern))
+            if not hits:
+                raise RuntimeError(f"sherpa KWS model file missing: {d}/{pattern}")
+            return str(hits[0])
+
+        self._spotter = sherpa_onnx.KeywordSpotter(
+            tokens=str(d / "tokens.txt"),
+            encoder=_model_file("encoder-*[!8].onnx"),
+            decoder=_model_file("decoder-*[!8].onnx"),
+            joiner=_model_file("joiner-*[!8].onnx"),
+            keywords_file=self._keywords_file,
+            keywords_threshold=threshold,
+            num_threads=1,
+        )
+        self._stream = self._spotter.create_stream()
+
+    def process(self, frame) -> bool:
+        import numpy as np
+
+        samples = np.asarray(frame, dtype=np.float32) / 32768.0
+        self._stream.accept_waveform(SAMPLE_RATE, samples)
+        fired = False
+        while self._spotter.is_ready(self._stream):
+            self._spotter.decode_stream(self._stream)
+            if self._spotter.get_result(self._stream):
+                fired = True
+                # Reset decoder state so one utterance can't fire repeatedly.
+                self._spotter.reset_stream(self._stream)
+        return fired
+
+    def reset(self) -> None:
+        # Fresh stream drops all buffered audio/decoder state (pause → resume
+        # must not re-fire on stale audio).
+        try:
+            self._stream = self._spotter.create_stream()
+        except Exception:
+            pass
+
+    def close(self) -> None:
+        try:
+            os.unlink(self._keywords_file)
+        except OSError:
+            pass
+
+
 class _PorcupineEngine(_Engine):
    """Picovoice Porcupine — premium, on-device, needs an access key."""

@ -269,6 +406,8 @@ def _build_engine(cfg: Dict[str, Any]) -> _Engine:
    provider = _provider(cfg)
    if provider == "porcupine":
        return _PorcupineEngine(cfg)
+    if provider in ("sherpa", "sherpa-onnx", "kws", "open"):
+        return _SherpaKwsEngine(cfg)
    if provider in ("openwakeword", "oww", "local"):
        return _OpenWakeWordEngine(cfg)
    raise ValueError(f"Unknown wake_word provider: {provider!r}")
@ -284,7 +423,12 @@ def check_wake_word_requirements(cfg: Optional[Dict[str, Any]] = None) -> Dict[s
    provider = _provider(cfg)
    from tools import lazy_deps

-    feature = "wake.porcupine" if provider == "porcupine" else "wake.openwakeword"
+    if provider == "porcupine":
+        feature = "wake.porcupine"
+    elif provider in ("sherpa", "sherpa-onnx", "kws", "open"):
+        feature = "wake.sherpa"
+    else:
+        feature = "wake.openwakeword"
    deps_ok = lazy_deps.is_available(feature)
    audio_ok = _audio_available()
    key_ok = True
--- a/uv.lock
+++ b/uv.lock
@ -1723,6 +1723,8 @@ wake = [
    { name = "onnxruntime" },
    { name = "openwakeword" },
    { name = "pvporcupine" },
+    { name = "sentencepiece" },
+    { name = "sherpa-onnx" },
    { name = "sounddevice" },
 ]
 web = [
@ -1845,7 +1847,9 @@ requires-dist = [
    { name = "rich", specifier = "==14.3.3" },
    { name = "ruamel-yaml", specifier = "==0.18.17" },
    { name = "ruff", marker = "extra == 'dev'", specifier = "==0.15.10" },
+    { name = "sentencepiece", marker = "extra == 'wake'", specifier = "==0.2.2" },
    { name = "setuptools", marker = "extra == 'dev'", specifier = "==81.0.0" },
+    { name = "sherpa-onnx", marker = "extra == 'wake'", specifier = "==1.13.4" },
    { name = "simple-term-menu", marker = "extra == 'cli'", specifier = "==1.6.6" },
    { name = "slack-bolt", marker = "extra == 'messaging'", specifier = "==1.29.0" },
    { name = "slack-bolt", marker = "extra == 'slack'", specifier = "==1.29.0" },
@ -4026,6 +4030,42 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/70/3a/21154e2d54eb3639c6bf4dbae2e531c68356bfe95990daa30df33b30d556/scipy-1.18.0-cp313-cp313-win_arm64.whl", hash = "sha256:c5dbddf60e58c2312316d097271a8e73d40eaf2eabfa4d95ed7d3695bbf2ce7b", size = 24350911, upload-time = "2026-06-19T15:00:40.062Z" },
 ]

+[[package]]
+name = "sentencepiece"
+version = "0.2.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cc/33/ea3cb3839607eb175da835244a798f797f478c5ddf0e8ecdf57ea85a4c70/sentencepiece-0.2.2.tar.gz", hash = "sha256:3d2b5e824b5622038dc7b490897efe05ebbbb9e7350fc142f3ecc8789ef9bdf6", size = 8218435, upload-time = "2026-07-12T08:39:34.701Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/31/f23a2efaa0210b883574001b88fa64e499f798f0848a0b610fb9b384d162/sentencepiece-0.2.2-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:69e9dc8078e128286ed3b975e37c837ba96e215a50c3ef9f3f8b7ab9e5a832a0", size = 2184255, upload-time = "2026-07-12T08:38:14.855Z" },
+    { url = "https://files.pythonhosted.org/packages/96/f2/1ee0ccb772d71e822f625d6cb5f0ea825835e877f28a9ef299a1291df19e/sentencepiece-0.2.2-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6dd76f3e5c8b2eb8a3a3efee787bbf5b9a66e52a048fe09cab85eca33fec6790", size = 1438545, upload-time = "2026-07-12T08:38:16.674Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/92/3a6ea4a2c6dd9e7062698a5a33534ca0e20844883338ae9c6b9c122c1a9f/sentencepiece-0.2.2-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:443ac618c7a2a1377cf5c82581fbb849591d14e656d5e5a3e4682d4e36a34e4e", size = 1346997, upload-time = "2026-07-12T08:38:18.499Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/3a/7839048997c7bc0c34c57526f539f835e20c7a57dc2a99f99579b11cdbef/sentencepiece-0.2.2-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0e2aae42960392d6dcb9a72d8e1e65a97294c965071b43c7b3429a42f350250e", size = 1324282, upload-time = "2026-07-12T08:38:20.342Z" },
+    { url = "https://files.pythonhosted.org/packages/06/5f/9117bf854aef817ad0d0ee9310eed0308a7e529e7eaf2e80ad9cd281ef82/sentencepiece-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:1416b92f2f010333786fe6306ed2631121d5ea492219b0841e967b6765e64107", size = 1394242, upload-time = "2026-07-12T08:38:22.976Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/62/9e2569867e3dcff7ad6d89642a9615b9801b5cd698abe7df3b490361f66e/sentencepiece-0.2.2-cp311-cp311-win_amd64.whl", hash = "sha256:70d4ca6f4d06df7f0ccab6fe4f49c8a712c8c8b6847b4f0af9a0e1dbb0e0337e", size = 1246268, upload-time = "2026-07-12T08:38:24.857Z" },
+    { url = "https://files.pythonhosted.org/packages/96/c9/5d781d4ef1124564a45c98b9ff25d531c10cdf568ec6314a2d1946f9251c/sentencepiece-0.2.2-cp311-cp311-win_arm64.whl", hash = "sha256:252908153eeec06c3ca3a32077e64a49d572e3d89881475b4e0f02d99d9fcc7c", size = 1190702, upload-time = "2026-07-12T08:38:26.789Z" },
+    { url = "https://files.pythonhosted.org/packages/b8/13/7a562289c8d5b49ebdf3f9c1e8ab67cf14a8743b1d90c8f406bfdec36b72/sentencepiece-0.2.2-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:1edb10e520e4bddf74d85b0f5ae74cc2d60c2b448885080bfb618bc2b3a49f6b", size = 2188384, upload-time = "2026-07-12T08:38:28.486Z" },
+    { url = "https://files.pythonhosted.org/packages/85/d1/912f14fd5eae168aba726ffb6a9a2dc1c71fe7676c53da6f5c442b886d4a/sentencepiece-0.2.2-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:f7c06c751c19d923435a54bff4f7e66e728fad160e8da28254f133abc9725820", size = 1441553, upload-time = "2026-07-12T08:38:30.552Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/44/caa9cab5f261a019e2808bc5046152775dc57352ba9cbae7525e9e7a1ed4/sentencepiece-0.2.2-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:38111ed1f79268f399c505028023d5eaaf0ab4e5eafceb709468b0d3323e7838", size = 1347176, upload-time = "2026-07-12T08:38:32.211Z" },
+    { url = "https://files.pythonhosted.org/packages/19/90/cd798935668cff71d309d8ff10385844ecf216b1fe454f1993ed8bf2cb91/sentencepiece-0.2.2-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:cbce24284f51f71d10a42b7b9c964dcb9048b28f1c8e5db40bcbcb6f428cba6a", size = 1325200, upload-time = "2026-07-12T08:38:33.689Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/2d/37e3da037318a70066ded0d51bc2a7f35491ae6338dd993d5eb1503fc3b5/sentencepiece-0.2.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c8a168b040bc61681293f79a949b5d911c8e25086f4260285b8d97ab5f1195da", size = 1397736, upload-time = "2026-07-12T08:38:35.771Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/11/753fca2e6b109be3ab7867abf357dfe48677fe726ae5a5363d0b54ca9450/sentencepiece-0.2.2-cp312-cp312-win_amd64.whl", hash = "sha256:7c6e7bf684dc12145bfa685d3060beaea55139134ba848289bee514ed42e7383", size = 1248030, upload-time = "2026-07-12T08:38:37.604Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/0a/70efbe861ca182d7d4b6e1a20f58e043400848fa9f2915229f082e221648/sentencepiece-0.2.2-cp312-cp312-win_arm64.whl", hash = "sha256:76ff5814db72e7462dece042d7593cdf102b8ec82c2b1cc201a2add34ee3050d", size = 1187325, upload-time = "2026-07-12T08:38:39.348Z" },
+    { url = "https://files.pythonhosted.org/packages/b9/a3/b3b05095c174d6e80d37d5ddc2f57c2c56237333e7bbd6079cf3243c2a8a/sentencepiece-0.2.2-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:77c3ce990b23441e5ecfa5bce181fd6f408b564aeb6d7e1d1e7de9c5612501c8", size = 2188346, upload-time = "2026-07-12T08:38:41.089Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/f3/72ebc4acb10a06bcf7503fbc6091c8f5db68300f6aac4356c09e6c76e0e1/sentencepiece-0.2.2-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:fd523c4992041faa5c2b3cde62253d11a96c30d73a34afe48a486e8e2254cd1c", size = 1441434, upload-time = "2026-07-12T08:38:42.56Z" },
+    { url = "https://files.pythonhosted.org/packages/34/db/f9ea1a6844b4fa5dfe2312095cd866a1f724cd0905054ab9d5991778ba50/sentencepiece-0.2.2-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:201a8e0f55501a76e08dbf2c54bc45f4642b379271e89c667d517bfbc2191f2a", size = 1347267, upload-time = "2026-07-12T08:38:44.389Z" },
+    { url = "https://files.pythonhosted.org/packages/32/4f/31c1073314ad94466bca37d29581761d70110237ee3d46b0efece59a8c1e/sentencepiece-0.2.2-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8eed98514bffe5ecac37f493f91869c351fbb05629328bfdbc08502c6c094dc0", size = 1324980, upload-time = "2026-07-12T08:38:46.304Z" },
+    { url = "https://files.pythonhosted.org/packages/59/b4/a0356fa04d6a14337a6e0e443556785a0422c53ec58baae6b9568120eb0f/sentencepiece-0.2.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:64b656f025355cf8c51abe9fbe3848540756c6d7ca5e6791b1afa664bc24c7cb", size = 1397593, upload-time = "2026-07-12T08:38:48.302Z" },
+    { url = "https://files.pythonhosted.org/packages/09/fa/d2d6369257fd2f0de616b1c7110b73fab409ef61b14f1b9e0010ed325914/sentencepiece-0.2.2-cp313-cp313-win_amd64.whl", hash = "sha256:74f0ee601047c0c12a783088b51be4e6214a62ecd9e02278c477433cd16e0ed9", size = 1247987, upload-time = "2026-07-12T08:38:50.15Z" },
+    { url = "https://files.pythonhosted.org/packages/17/ee/2bb594da6fd95e32f29057f1aa7fa996701b8980090923c2d8711fdc0a24/sentencepiece-0.2.2-cp313-cp313-win_arm64.whl", hash = "sha256:b23fe17779834d3c27aaf2edac9486d04cca1a7deb8f5facda35150ac6263a91", size = 1187250, upload-time = "2026-07-12T08:38:52.246Z" },
+    { url = "https://files.pythonhosted.org/packages/58/9c/dfc82846460e7a712310f5613f23d8b553cabb4e2e648663c11d8382af56/sentencepiece-0.2.2-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:72b7825b331b1b7e7c45be2e674b3e3c65af608fa376bad2d851b20aaf0cdc78", size = 2223080, upload-time = "2026-07-12T08:38:54.391Z" },
+    { url = "https://files.pythonhosted.org/packages/8d/4e/3ff12cebe6d31662d9ceeabfb282de20bd0d6098fa282b4a3b8305abc7e8/sentencepiece-0.2.2-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:d795c4ac689a57f9d4ba2288126ec7901d389ad5827d2f8b8533c883974fe563", size = 1458511, upload-time = "2026-07-12T08:38:56.811Z" },
+    { url = "https://files.pythonhosted.org/packages/59/5a/16d51d05360be4cee3ebfe4837c184054c4eed16cabaeb3b039524e9a000/sentencepiece-0.2.2-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:3ab3f1ae98970b5590e2209341522718900ba19bcc2c207ffaa6bd417ad960c5", size = 1361138, upload-time = "2026-07-12T08:38:58.808Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/af/c30ee2a9f99d51db9844acaa8fa0b611a97c2fa7116646fa43db3300b187/sentencepiece-0.2.2-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3ec27c152a1f1b24bc9168b55a5880f3c16e2334e697da6f55a1046a22405a3d", size = 1328625, upload-time = "2026-07-12T08:39:00.849Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/1a/4c6b39d03f5ba8439509adbd5a23c9538088a3cb679e7a47b911e8442bc6/sentencepiece-0.2.2-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:59d6588712101ccfcae9b03692be3aaae1514c2078666d7b05f15ba3a702e41b", size = 1398595, upload-time = "2026-07-12T08:39:02.86Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/bc/9eedddcec1fd57bc70200fa3ebf792d18fa63527a5369581cd416c81f97f/sentencepiece-0.2.2-cp313-cp313t-win_amd64.whl", hash = "sha256:89625fb43765cccaa1443b9adb61f283e5fe4cb1536728205d06bada730caa53", size = 1259346, upload-time = "2026-07-12T08:39:04.559Z" },
+    { url = "https://files.pythonhosted.org/packages/41/15/7e74c8533848866ff560b29f7d8719921b76c4ec7149592d6d28e0deee75/sentencepiece-0.2.2-cp313-cp313t-win_arm64.whl", hash = "sha256:4f0603267cd15b92b68c2c0e852a441507614b70dc7773659baa6b8c214a91fd", size = 1196596, upload-time = "2026-07-12T08:39:06.454Z" },
+]
+
 [[package]]
 name = "setuptools"
 version = "81.0.0"
@ -4044,6 +4084,38 @@ wheels = [
    { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
 ]

+[[package]]
+name = "sherpa-onnx"
+version = "1.13.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ca/f8/735244770b4bc63f85fabdad0e46d6ec1f4cc24e64f6e082c2e0fea92b8c/sherpa_onnx-1.13.4.tar.gz", hash = "sha256:29547692418513ad88034c2b5f98985e33042b2351e4ab375469f19a8de18c5f", size = 982750, upload-time = "2026-07-07T13:04:55.145Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2a/4f/6ab541c5b2a4b2a6e9970edc4b558f270f7b6624c861eccb85126ccd279c/sherpa_onnx-1.13.4-cp311-cp311-linux_armv7l.whl", hash = "sha256:8e1cdbd53b432630a81ea479ce5bad6aa8192eb4a458d8c9432c54052cb9cc7d", size = 11930819, upload-time = "2026-07-07T14:22:29.536Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/41/b750ec336f882e75c5e23c9ad5d52b0902be2337cc50d13ce68cde9e4459/sherpa_onnx-1.13.4-cp311-cp311-macosx_10_15_universal2.whl", hash = "sha256:5d35aeb5ad13b54cea0d6fed681660f6308acb841de981745e33d457255b9134", size = 4349088, upload-time = "2026-07-07T13:14:19.408Z" },
+    { url = "https://files.pythonhosted.org/packages/41/c8/a2ff828ce9a2702b607c25f6303b21d7d41b6ad1520f660b95a0113f4051/sherpa_onnx-1.13.4-cp311-cp311-macosx_10_15_x86_64.whl", hash = "sha256:c3e9f96a07570faefca8e3aabcfb78690e680d188d5d44d06fd8711185fe37d6", size = 2288314, upload-time = "2026-07-07T12:08:36.643Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/93/4385fcdb1f197521fe13fa887893cc200d27569d3cbcccf0d7b92d6a9e62/sherpa_onnx-1.13.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:c2d4337b80b54dd68f566cab941a2ad47ab6cfabb68e88002ee0c920493c16d3", size = 2100029, upload-time = "2026-07-07T12:23:26.936Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/cb/c80832f800719c72fc5805a94fe489e805fc67156e102927609917ad8f67/sherpa_onnx-1.13.4-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7c4a1c178eb801af92f70120128c1f956b5388b9d684f0af2a08614e05dc3047", size = 4132838, upload-time = "2026-07-07T11:55:17.567Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/ac/88b4e1ce614ddebe2484e95cad4b19d7db24f3b489d04f9877667cb48ccb/sherpa_onnx-1.13.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fbfc385b98d730080e1b12dc94c604be3867e4fb7bd6b15b830eb33cbf390111", size = 4356406, upload-time = "2026-07-07T12:42:29.823Z" },
+    { url = "https://files.pythonhosted.org/packages/b5/73/2fff5d28669e91851e981d223c50aa21f90d712a4551dcb51c231b3a27fe/sherpa_onnx-1.13.4-cp311-cp311-win32.whl", hash = "sha256:1d746b8c6ed1ce9eb94868d71b5ea9c22274b8cb166420bd1772f7df470b753a", size = 1927745, upload-time = "2026-07-07T12:33:50.17Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/b1/ae1c113ac9c67dcabbed559f50950c7220a62e49e6b5acb4c2219ab22409/sherpa_onnx-1.13.4-cp311-cp311-win_amd64.whl", hash = "sha256:04a82d79c13a4ce2bd9ccf51de93e83cbfc7bc50520c53e5e967565100d0724d", size = 2239901, upload-time = "2026-07-07T12:22:27.112Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/57/179e3a6c1fec33aa6535051feddd5da36e5622d35630b12a67a2805b76b3/sherpa_onnx-1.13.4-cp312-cp312-linux_armv7l.whl", hash = "sha256:bcf64f2d853a1afe236e9e220df62f2f53ef6ad792ca7e406d6173ec003319b8", size = 11933213, upload-time = "2026-07-07T13:50:35.989Z" },
+    { url = "https://files.pythonhosted.org/packages/e8/34/b6d3483b08ec8a4a141e978c4b92530fd0a61dd571a575c1fe24bee300d7/sherpa_onnx-1.13.4-cp312-cp312-macosx_10_15_universal2.whl", hash = "sha256:2257545ea170f58b7977309793979d6d078761b7fdb0528561285f8ead4169db", size = 4422157, upload-time = "2026-07-07T12:29:40.234Z" },
+    { url = "https://files.pythonhosted.org/packages/82/37/07f03e97f157b206f6e62d722ec7c5ff41c7e9dc6aa2dc7de69b57e39b5a/sherpa_onnx-1.13.4-cp312-cp312-macosx_10_15_x86_64.whl", hash = "sha256:02b57dc2c829976eb842e6aee6a0e4ac3b9991aeb5afa89fd44eb71d848a4ecd", size = 2345135, upload-time = "2026-07-07T12:10:19.957Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/79/ee999f0c3b7789077d0939716a38234573d139f851a31409aa028fe2c610/sherpa_onnx-1.13.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:84e58b5a074b97c5307c9b6221d1d20fbf412a1a5dff4960ca9c32bb5184219f", size = 2105219, upload-time = "2026-07-07T11:48:22.518Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/90/9b67ed3e7adc79daf0ba49c4936a691521488125b04fe469b64a8b5398ff/sherpa_onnx-1.13.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f709e6dd02ebf7d37dcb02d5eadc5fb66c9922dd5809df770c1ef5d625ae7a44", size = 4135963, upload-time = "2026-07-07T11:58:30.98Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/b1/8dfe5d1d72c92ea1c95db999a95b61bfbb9769f1c569f06e572eda095c52/sherpa_onnx-1.13.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:5f0158f3513d3adab1ebba0c26f0c815e53ba13b96846d92ef095ae25d648860", size = 4358555, upload-time = "2026-07-07T12:58:59.654Z" },
+    { url = "https://files.pythonhosted.org/packages/d4/04/cfd543933ae24430d124e533847c73a84a5f0efd60f07bbc6403032f9624/sherpa_onnx-1.13.4-cp312-cp312-win32.whl", hash = "sha256:d49928a3455bae1dd4e93f6b013cfbd2c3ccb5cde74aabae3710b656e7d79b6b", size = 1930647, upload-time = "2026-07-07T12:02:06.689Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/bb/1e723ab703a1e354f390de19981ec0c347576f87be01915d826dc6fc9f41/sherpa_onnx-1.13.4-cp312-cp312-win_amd64.whl", hash = "sha256:b8436ffe2763b3fd522fbac8fe53f47d611721c84819c241acfb65d122403d7d", size = 2244142, upload-time = "2026-07-07T13:01:42.293Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/36/45b17335f041f1383f6fd142ab57c2d8a337ba2386b7547b125ec9d780af/sherpa_onnx-1.13.4-cp313-cp313-linux_armv7l.whl", hash = "sha256:9e98dc5e0559ad953f227fc884958c71b10c65a93667331405e7d4441ed5f76d", size = 11932654, upload-time = "2026-07-07T14:18:59.791Z" },
+    { url = "https://files.pythonhosted.org/packages/68/d7/1e9a7dedab2da8af1a8417b4f4d5f496bd7700a71b59c5e085de5e10761b/sherpa_onnx-1.13.4-cp313-cp313-macosx_10_15_universal2.whl", hash = "sha256:083747c2d0362ead0501cc773a618be19862a800b3f8f259d3bd3486f1494af4", size = 4372494, upload-time = "2026-07-07T13:02:05.512Z" },
+    { url = "https://files.pythonhosted.org/packages/62/28/09aa9461e8bdf894ba8466e047e40fb5da8aaa6d68c19cf1e2aabe01e706/sherpa_onnx-1.13.4-cp313-cp313-macosx_10_15_x86_64.whl", hash = "sha256:b4f54363b264b16148a724b4442f00cda97fcd4e9beeda3d75637753910e8557", size = 2307539, upload-time = "2026-07-07T12:28:22.056Z" },
+    { url = "https://files.pythonhosted.org/packages/21/ed/d07787dd4be4119e6587c840f6b417c2d57c14d694d334af609d68cb5a41/sherpa_onnx-1.13.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:8ec5394b4ea73bf01e6883cf078348f87350f4eb3567d51d92cae77ea2582403", size = 2115586, upload-time = "2026-07-07T12:47:31.367Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/c2/281d84dc9e448ea99d7fb77708cbe1cc7cfd8c7d669727dc94385a9e4ca5/sherpa_onnx-1.13.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:a39352ceb2ec6671a1f252fb768fff75bb2f0bc849cca5f66f490e89910a860d", size = 4136268, upload-time = "2026-07-07T12:10:09.762Z" },
+    { url = "https://files.pythonhosted.org/packages/db/47/da3ea14ab647a4f6580227853fe29353e1173ff77064d42c0bb31d01b453/sherpa_onnx-1.13.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:88af596be24eac32982dd64fcac30af99d9130ca498bfa1a0064189c8498195b", size = 4358385, upload-time = "2026-07-07T13:10:10.265Z" },
+    { url = "https://files.pythonhosted.org/packages/44/90/84205ff383ba9335c3821c2cd6d514350f52199cb640ec094517f1f911a0/sherpa_onnx-1.13.4-cp313-cp313-win32.whl", hash = "sha256:0cabb508a15be22138f9fb7695d7ec5f3893ecd088ee419b9df559fed7e8f649", size = 1929707, upload-time = "2026-07-07T12:51:53.196Z" },
+    { url = "https://files.pythonhosted.org/packages/82/40/ee8a0a8c83fc6d7f5245a5a031e471d3b115e20cce867e7abb2f9d4185c9/sherpa_onnx-1.13.4-cp313-cp313-win_amd64.whl", hash = "sha256:17050fdfb48d37ae996364f697c554a1399740d18e5a56b143c011d00cfed3e0", size = 2244504, upload-time = "2026-07-07T12:32:59.882Z" },
+]
+
 [[package]]
 name = "simple-term-menu"
 version = "1.6.6"
--- a/website/docs/user-guide/features/wake-word.md
+++ b/website/docs/user-guide/features/wake-word.md
@ -33,6 +33,7 @@ It is **off by default** — nothing listens until you turn it on.
 | Engine | Cost | API key | Notes |
 |--------|------|---------|-------|
 | **openWakeWord** (default) | Free | None | Local ONNX models. Ships a bundled **"hey hermes"** model (default); also supports `hey_jarvis`, `alexa`, `hey_mycroft`, … and custom models |
+| **sherpa** | Free | None | **Open vocabulary** — detects ANY typed phrase with zero training. Small English model auto-downloads on first use (~13 MB) |
 | **Porcupine** | Free tier / paid | `PORCUPINE_ACCESS_KEY` | Picovoice engine; built-in keywords + custom `.ppn` files |

 By default the phrase is **"hey hermes"** — a model for it ships with Hermes, so
@ -106,14 +107,29 @@ command records.
 ## Using a different phrase

 "Hey Hermes" works out of the box — the bundled openWakeWord model
-(`model: hey_hermes`) is the default. To wake on something else, either name a
-built-in openWakeWord model or supply your own:
+(`model: hey_hermes`) is the default. To wake on something else, the easiest
+path is the open-vocabulary engine:

-### Option A — openWakeWord (free)
+### Option A — sherpa (any phrase, zero training)
+
+Type the phrase you want; it's tokenized at runtime — "hey coder",
+"computer", "wake up neo", anything:
+
+```yaml
+wake_word:
+  enabled: true
+  provider: sherpa
+  phrase: "hey coder"        # detection key — just type your phrase
+```
+
+The small English KWS model (~13 MB) downloads once on first use. Each
+profile can set its own phrase — "hey \<profile\>" for every profile you run.
+
+### Option B — openWakeWord (free, trained model)

 Name a built-in model (`hey_jarvis`, `alexa`, `hey_mycroft`, …), or train a
-custom model (≈75–90 min on a free/Colab GPU), drop the `.onnx` file somewhere,
-and reference it:
+custom model (≈75–90 min on a free/Colab GPU) for maximum robustness, drop
+the `.onnx` file somewhere, and reference it:

 ```yaml
 wake_word:
@ -135,7 +151,7 @@ syllables with an uncommon word ("hermes" qualifies) beat common words like
 "hello" or "stop".
 :::

-### Option B — Porcupine (custom keyword in seconds)
+### Option C — Porcupine (custom keyword in seconds)

 Create a "Hey Hermes" keyword in the [Picovoice Console](https://console.picovoice.ai/),
 download the `.ppn`, and: