Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

perf(wake): load the wake runtime without its verifier-training stack (#651)

Ruben Lütke428df43de9c0
diff --git a/jarvis/plugins/wake/openwakeword_provider.py b/jarvis/plugins/wake/openwakeword_provider.py
index 21e2b61d94..53da29818e 100644
--- a/jarvis/plugins/wake/openwakeword_provider.py
+++ b/jarvis/plugins/wake/openwakeword_provider.py
@@ -14,9 +14,13 @@ Output: continuous score [0, 1] per keyword — we filter on
from __future__ import annotations
import asyncio
+import contextlib
import logging
+import sys
+import threading
import time
-from collections.abc import AsyncIterator
+import types
+from collections.abc import AsyncIterator, Iterator
import numpy as np
@@ -26,6 +30,70 @@ from jarvis.core.protocols import AudioChunk
log = logging.getLogger("jarvis.wake")
+_OWW_TRAINING_MODULE = "openwakeword.custom_verifier_model"
+#: The boot prefetch thread and the provider both load the runtime; one at a
+#: time, so a fallback never purges modules another caller is importing.
+_OWW_IMPORT_LOCK = threading.Lock()
+
+
+def _train_custom_verifier_unavailable(*_args: object, **_kwargs: object) -> None:
+ raise RuntimeError(
+ "openWakeWord verifier training was not loaded with the wake runtime; "
+ f"import {_OWW_TRAINING_MODULE} directly to use it."
+ )
+
+
+def _inference_only_openwakeword_import() -> Iterator[None]:
+ """Keep the verifier-training stack out of the first openWakeWord import.
+
+ ``openwakeword/__init__`` imports ``custom_verifier_model`` for its
+ ``train_custom_verifier`` helper, and that module imports scipy and
+ scikit-learn (which imports pandas and pyarrow where they are installed).
+ Scoring a wake model touches none of it: the provider never passes
+ ``custom_verifier_models``. Measured 2026-10-13 on top of numpy and
+ onnxruntime: 107 MB private memory and 1.4 s for the plain import (78 MB
+ and 1.1 s without pandas), 13 MB and 0.2 s with the stand-in below.
+
+ Only a module that is not really imported yet is replaced, and only the
+ stand-in set here is removed again, so a later explicit import of the
+ training module still loads the real one.
+ """
+ if _OWW_TRAINING_MODULE in sys.modules or "openwakeword" in sys.modules:
+ yield
+ return
+ stand_in = types.ModuleType(_OWW_TRAINING_MODULE)
+ stand_in.train_custom_verifier = _train_custom_verifier_unavailable # type: ignore[attr-defined]
+ sys.modules[_OWW_TRAINING_MODULE] = stand_in
+ try:
+ yield
+ finally:
+ if sys.modules.get(_OWW_TRAINING_MODULE) is stand_in:
+ del sys.modules[_OWW_TRAINING_MODULE]
+
+
+def load_openwakeword_model_class() -> type:
+ """Import ``openwakeword.model.Model`` without the training-only stack.
+
+ Any failure of the lean import is retried as the plain one, so a future
+ openWakeWord layout costs the saving, never the wake word. A runtime that
+ is genuinely absent raises its ``ImportError`` from that second attempt.
+ """
+ with _OWW_IMPORT_LOCK:
+ before = set(sys.modules)
+ try:
+ with _inference_only_openwakeword_import():
+ from openwakeword.model import Model
+ except Exception as exc: # noqa: BLE001 — retried in full right below
+ log.debug("Lean openWakeWord import failed (%s); retrying in full", exc)
+ # Drop only what this attempt left half-imported.
+ for name in set(sys.modules) - before:
+ if name == "openwakeword" or name.startswith("openwakeword."):
+ del sys.modules[name]
+ from openwakeword.model import Model
+ return Model
+
+
OWW_SAMPLE_RATE = 16_000
OWW_FRAME_SAMPLES = 1280 # openWakeWord expects exactly this frame length
@@ -303,7 +371,7 @@ class OpenWakeWordProvider:
if self._model is not None or self._runtime_unavailable:
return
try:
- from openwakeword.model import Model
+ Model = load_openwakeword_model_class() # noqa: N806 — a class
except ImportError as exc:
# openwakeword + onnxruntime are BASE deps, so this only happens on a
# broken/partial install. Degrade to a no-op wake (the pipeline keeps
diff --git a/jarvis/speech/warmup_prefetch.py b/jarvis/speech/warmup_prefetch.py
index f351d29a7d..523125e8b7 100644
--- a/jarvis/speech/warmup_prefetch.py
+++ b/jarvis/speech/warmup_prefetch.py
@@ -67,7 +67,13 @@ def prefetch_wake_imports(importer: Callable[[], None] | None = None) -> bool:
"""
def _default_import() -> None:
- import openwakeword.model # noqa: F401, PLC0415 — eager warm import
+ # Through the provider's loader, so the prefetch leaves the same lean
+ # module set behind that the provider itself would import.
+ from jarvis.plugins.wake.openwakeword_provider import ( # noqa: PLC0415
+ load_openwakeword_model_class,
+ )
+
+ load_openwakeword_model_class()
do_import = importer or _default_import
try:
diff --git a/tests/unit/plugins/wake/test_openwakeword_lean_import.py b/tests/unit/plugins/wake/test_openwakeword_lean_import.py
new file mode 100644
index 0000000000..760d3b111f
--- /dev/null
+++ b/tests/unit/plugins/wake/test_openwakeword_lean_import.py
@@ -0,0 +1,166 @@
+"""The wake runtime loads without openWakeWord's verifier-training stack.
+
+``openwakeword/__init__`` imports ``custom_verifier_model`` (scipy +
+scikit-learn, and pandas + pyarrow where installed) for a training helper the
+wake path never calls. The provider's loader keeps that out of the process:
+about 95 MB of private memory and over a second of import time on the boot
+path. These tests pin that the saving holds, that scoring still works, and
+that a failing lean import falls back to the plain one instead of costing the
+wake word.
+"""
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import subprocess
+import sys
+from collections.abc import Iterator
+
+import pytest
+
+from jarvis.plugins.wake import openwakeword_provider as provider_module
+from jarvis.plugins.wake.openwakeword_provider import (
+ OpenWakeWordProvider,
+ _train_custom_verifier_unavailable,
+ load_openwakeword_model_class,
+)
+
+needs_openwakeword = pytest.mark.skipif(
+ importlib.util.find_spec("openwakeword") is None,
+ reason="openwakeword not installed in this environment",
+)
+
+
+def _run_fresh(script: str) -> subprocess.CompletedProcess[str]:
+ """Run in a fresh interpreter: another test may have imported the full stack."""
+ return subprocess.run(
+ [sys.executable, "-c", script],
+ capture_output=True,
+ text=True,
+ timeout=180,
+ )
+
+
+@needs_openwakeword
+def test_loader_keeps_the_training_stack_out_of_the_process() -> None:
+ script = (
+ "import sys\n"
+ "from jarvis.plugins.wake.openwakeword_provider import (\n"
+ " load_openwakeword_model_class,\n"
+ ")\n"
+ "model_class = load_openwakeword_model_class()\n"
+ "assert model_class.__name__ == 'Model', model_class\n"
+ "loaded = [m for m in ('sklearn', 'pandas', 'pyarrow') if m in sys.modules]\n"
+ "assert not loaded, f'training stack imported: {loaded}'\n"
+ "assert 'openwakeword.custom_verifier_model' not in sys.modules\n"
+ "print('OK')\n"
+ )
+ res = _run_fresh(script)
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"
+
+
+@needs_openwakeword
+def test_training_module_still_imports_for_real_afterwards() -> None:
+ script = (
+ "import sys\n"
+ "from jarvis.plugins.wake.openwakeword_provider import (\n"
+ " load_openwakeword_model_class,\n"
+ ")\n"
+ "load_openwakeword_model_class()\n"
+ "import openwakeword.custom_verifier_model as real\n"
+ "assert hasattr(real, 'LogisticRegression'), 'stand-in leaked'\n"
+ "print('OK')\n"
+ )
+ res = _run_fresh(script)
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"
+
+
+@needs_openwakeword
+def test_lean_runtime_scores_a_frame_with_the_bundled_backbones() -> None:
+ """The model the lean import returns still loads and scores audio."""
+ script = (
+ "import sys\n"
+ "from pathlib import Path\n"
+ "import numpy as np\n"
+ "import jarvis.assets\n"
+ "from jarvis.plugins.wake.openwakeword_provider import (\n"
+ " OWW_FRAME_SAMPLES,\n"
+ " load_openwakeword_model_class,\n"
+ ")\n"
+ "model_class = load_openwakeword_model_class()\n"
+ "import openwakeword\n"
+ "resources = Path(openwakeword.__file__).parent / 'resources' / 'models'\n"
+ "backbones = ('embedding_model', 'melspectrogram', 'silero_vad')\n"
+ "candidates = sorted(\n"
+ " p for p in resources.glob('*.onnx') if p.stem not in backbones\n"
+ ")\n"
+ "if not candidates:\n"
+ " print('SKIP')\n"
+ " raise SystemExit(0)\n"
+ "kwargs = {'wakeword_models': [str(candidates[0])],\n"
+ " 'inference_framework': 'onnx'}\n"
+ "bundled = jarvis.assets.bundled_wakeword_models()\n"
+ "if bundled is not None:\n"
+ " kwargs['melspec_model_path'] = str(bundled['melspec'])\n"
+ " kwargs['embedding_model_path'] = str(bundled['embedding'])\n"
+ "model = model_class(**kwargs)\n"
+ "scores = model.predict(np.zeros(OWW_FRAME_SAMPLES, dtype=np.int16))\n"
+ "assert scores and all(0.0 <= float(v) <= 1.0 for v in scores.values())\n"
+ "assert 'sklearn' not in sys.modules\n"
+ "print('OK')\n"
+ )
+ res = _run_fresh(script)
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"
+ if "SKIP" in res.stdout:
+ pytest.skip("no wake model file in the installed openwakeword package")
+
+
+@needs_openwakeword
+def test_failing_lean_import_falls_back_to_the_plain_one(monkeypatch) -> None:
+ @contextlib.contextmanager
+ def _broken() -> Iterator[None]:
+ raise RuntimeError("lean import is not possible on this layout")
+ yield # pragma: no cover
+
+ monkeypatch.setattr(provider_module, "_inference_only_openwakeword_import", _broken)
+
+ model_class = load_openwakeword_model_class()
+
+ assert model_class.__name__ == "Model"
+
+
+def test_missing_runtime_still_degrades_through_the_loader(monkeypatch) -> None:
+ """The retry must not undo a module that was unavailable before the call."""
+ monkeypatch.setitem(sys.modules, "openwakeword.model", None)
+ provider = OpenWakeWordProvider()
+
+ provider._ensure_model() # must NOT raise
+
+ assert provider._runtime_unavailable is True
+ assert sys.modules["openwakeword.model"] is None
+
+
+def test_stand_in_training_helper_fails_loudly() -> None:
+ with pytest.raises(RuntimeError, match="verifier training"):
+ _train_custom_verifier_unavailable()
+
+
+@needs_openwakeword
+def test_concurrent_loaders_get_the_same_class() -> None:
+ """The boot prefetch and the provider may load at once; both get one Model."""
+ script = (
+ "import sys, threading\n"
+ "from jarvis.plugins.wake.openwakeword_provider import (\n"
+ " load_openwakeword_model_class,\n"
+ ")\n"
+ "found = []\n"
+ "threads = [threading.Thread(target=lambda: found.append(\n"
+ " load_openwakeword_model_class())) for _ in range(4)]\n"
+ "[t.start() for t in threads]\n"
+ "[t.join(120) for t in threads]\n"
+ "assert len(found) == 4 and len(set(found)) == 1, found\n"
+ "assert 'sklearn' not in sys.modules\n"
+ "print('OK')\n"
+ )
+ res = _run_fresh(script)
+ assert res.returncode == 0, f"stdout={res.stdout}\nstderr={res.stderr}"