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.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(voice-engine): one-click engine setup in its own uv environment
rubenluetke10-beep9324ec8cf619
diff --git a/jarvis.spec b/jarvis.specindex 14f158fb09..29adeb4dab 100644--- a/jarvis.spec+++ b/jarvis.spec@@ -73,6 +73,15 @@ datas.append((str(PROJECT_ROOT / "jarvis/society/browser/live_runner.py"), "jarvdatas.append((str(PROJECT_ROOT / "jarvis/society/browser/native_window.py"), "jarvis/society/browser"))datas.append((str(PROJECT_ROOT / "jarvis/society/browser/pointer.py"), "jarvis/society/browser"))+# The local voice engine runs in its OWN Python environment, so a frozen build+# must ship its sources as plain files: setup copies them into the engine home+# (jarvis/realtime/local_voice_setup.py). Caches never ride along.+_VOICE_ENGINE = PROJECT_ROOT / "jarvis" / "voice_engine"+for entry in _VOICE_ENGINE.rglob("*"):+ if entry.is_file() and "__pycache__" not in entry.parts and entry.suffix != ".pyc":+ rel = entry.relative_to(_VOICE_ENGINE).parent+ datas.append((str(entry), str(Path("jarvis/voice_engine") / rel)))+# Include the frontend build when present. Preserve its package-relative layout# so the FastAPI static-files mount can serve it from a frozen application.if FRONTEND_DIST.exists():diff --git a/jarvis/realtime/local_voice_setup.py b/jarvis/realtime/local_voice_setup.pynew file mode 100644index 0000000000..cac834a014--- /dev/null+++ b/jarvis/realtime/local_voice_setup.py@@ -0,0 +1,742 @@+"""Set up, describe and prove the local voice engine on this machine (ADR-0037).++Everything the Local voice card needs lives here: the one-click setup that+builds the engine's own environment, the status the card renders, and the+self-test that proves a real round trip. Nothing in this module runs at boot:+setup starts only from the card (``POST /api/providers/local-voice/setup``),+and the status read only looks at files and the already-running engine.++Setup steps (``docs/local-live-voice-rebuild.md`` section 4.10):++1. ``uv`` — the pinned bootstrap binary (``jarvis.society.browser.bootstrap``).+2. ``python`` — ``uv venv`` with a uv-managed CPython 3.12 under the engine+ home, independent of the app's interpreter.+3. ``packages`` — ``jarvis/voice_engine/requirements-engine.txt`` with CPU torch.+4. ``engine`` — a copy of ``jarvis/voice_engine`` for frozen builds.+5. ``models`` — the speech models from the pinned registry, checksummed.+6. ``voice`` — Pocket TTS weights, fetched once so the worker runs offline.+7. ``llm`` — the language model in the local Ollama server, installed first.+8. ``selftest`` — start the engine and speak, hear and answer once.+"""++from __future__ import annotations++import asyncio+import hashlib+import json+import logging+import os+import shutil+import subprocess+import sys+import threading+import time+from collections.abc import Awaitable, Callable, Iterable+from concurrent.futures import Future+from dataclasses import dataclass, field+from pathlib import Path+from typing import Any++log = logging.getLogger(__name__)++#: Card phases. Mirrored by ``LOCAL_VOICE_PHASES`` in the frontend+#: (``src/lib/localVoice.ts``); ``tests/unit/realtime/test_local_voice_parity.py``+#: keeps the two in lockstep (AP-4).+PHASES: tuple[str, ...] = ("not_installed", "installing", "stopped", "starting", "ready", "failed")+#: Machine classes of plan section 4.8 (what decides the defaults).+MACHINE_CLASSES: tuple[str, ...] = ("nvidia", "apple", "gpu", "cpu")+#: Where an expected latency comes from: a bench run on that class, a+#: documented estimate, or nothing until this machine's self-test.+LATENCY_BASES: tuple[str, ...] = ("measured", "estimate", "selftest")+#: Setup stages in order, as the card names them.+SETUP_STAGES: tuple[str, ...] = (+ "uv", "python", "packages", "engine", "models", "voice", "llm", "selftest",+)++_STAGE_WEIGHTS: dict[str, float] = {+ "uv": 0.03, "python": 0.07, "packages": 0.35, "engine": 0.02,+ "models": 0.33, "voice": 0.10, "llm": 0.07, "selftest": 0.03,+}+#: The CPU-only default (plan section 12.3): first clause ~1.5 s on a CPU.+CPU_LLM = "qwen3.5:2b"+GPU_LLM = "qwen3.5:4b"+#: Installed-first candidates per class: an already downloaded model that+#: measured well beats a multi-gigabyte download (plan 12.3).+_LLM_CANDIDATES: dict[str, tuple[str, ...]] = {+ "gpu": (GPU_LLM, "granite4.2:8b", "gemma4:12b-it-qat", CPU_LLM),+ "cpu": (CPU_LLM, GPU_LLM),+}+#: Accelerator memory below this runs the CPU default (6-8 GB is the smallest+#: GPU class plan section 4.8 sizes for).+_GPU_MIN_GB = 6.0+_PYTHON_VERSION = "3.12"+_SETUP_STATE = "setup.json"+_SELFTEST_STATE = "selftest.json"+_COMMAND_TIMEOUT_S = 3600+_LLM_PULL_TIMEOUT_S = 3600.0+_SELFTEST_READY_TIMEOUT_S = 180.0+++class SetupError(RuntimeError):+ """A setup step failed; ``str()`` is one sentence for the card."""+++# ---------------------------------------------------------------- locations+++def engine_home() -> Path:+ from jarvis.voice_engine.paths import engine_home as _home # noqa: PLC0415++ return _home()+++def requirements_file() -> Path:+ return Path(__file__).resolve().parent.parent / "voice_engine" / "requirements-engine.txt"+++def requirements_sha256() -> str:+ try:+ return hashlib.sha256(requirements_file().read_bytes()).hexdigest()+ except OSError:+ return ""+++def engine_version() -> str:+ from jarvis.voice_engine import ENGINE_VERSION # noqa: PLC0415++ return ENGINE_VERSION+++def _read_json(path: Path) -> dict[str, Any]:+ try:+ data = json.loads(path.read_text(encoding="utf-8"))+ except (OSError, ValueError):+ return {}+ return data if isinstance(data, dict) else {}+++def _write_json(path: Path, payload: dict[str, Any]) -> None:+ path.parent.mkdir(parents=True, exist_ok=True)+ temporary = path.with_suffix(".tmp")+ temporary.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")+ os.replace(temporary, path)+++# ------------------------------------------------------------ machine class+++def platform_name() -> str:+ if sys.platform == "win32":+ return "windows"+ if sys.platform == "darwin":+ return "macos"+ return "linux"+++def machine_class(probe: Callable[[], tuple[float, str]] | None = None) -> str:+ """``nvidia`` | ``apple`` | ``gpu`` | ``cpu`` from the shared accelerator probe.++ Hardware only decides what to try; the self-test decides what works+ (plan section 4.8). A probe failure reads as ``cpu``: the slower, safe class.+ """+ if probe is None:+ from jarvis.hardware.detection import usable_accelerator_gb # noqa: PLC0415++ probe = usable_accelerator_gb+ try:+ gb, source = probe()+ except Exception: # noqa: BLE001 - a broken probe must not break the card+ log.warning("local voice: accelerator probe failed; assuming a CPU-only machine",+ exc_info=True)+ return "cpu"+ if gb < _GPU_MIN_GB:+ return "cpu"+ if source == "nvidia-smi":+ return "nvidia"+ if source == "apple-unified":+ return "apple"+ return "gpu"+++def default_llm(machine: str) -> str:+ return CPU_LLM if machine == "cpu" else GPU_LLM+++def _same_tag(a: str, b: str) -> bool:+ def norm(tag: str) -> str:+ tag = tag.strip()+ return tag[: -len(":latest")] if tag.endswith(":latest") else tag++ return norm(a) == norm(b)+++def choose_llm(machine: str, installed: Iterable[str]) -> tuple[str, bool]:+ """``(model, already installed)`` — installed models first, then the default.++ A candidate counts when its exact tag is installed; the class default is+ returned (to be pulled) only when no candidate is on this machine.+ """+ names = [str(n) for n in installed]+ for candidate in _LLM_CANDIDATES["cpu" if machine == "cpu" else "gpu"]:+ if any(_same_tag(candidate, name) for name in names):+ return candidate, True+ return default_llm(machine), False+++def expected_latency(machine: str) -> dict[str, Any]:+ """Speech end to first audio, with where the number comes from (plan 4.8, 12.4)."""+ if machine == "nvidia":+ # Bench e2e on a 16 GB NVIDIA card: dialog p50 749-856 ms (section 12.4).+ return {"low_s": 0.75, "high_s": 0.9, "basis": "measured"}+ if machine == "apple":+ return {"low_s": 1.2, "high_s": 1.8, "basis": "estimate"}+ if machine == "cpu":+ return {"low_s": 2.0, "high_s": 2.0, "basis": "estimate"}+ return {"low_s": None, "high_s": None, "basis": "selftest"}+++def os_verified(machine: str, platform: str | None = None) -> bool:+ """Whether the engine ever ran on this OS and machine class (plan section 11).++ P0/P1 ran on Windows with an NVIDIA card and in a CPU-only Linux+ container; everything else is honest "not verified yet".+ """+ return (platform or platform_name(), machine) in {("windows", "nvidia"), ("linux", "cpu")}+++# --------------------------------------------------------------- setup run+++@dataclass+class _Run:+ running: bool = False+ stage: str = ""+ progress: float = 0.0+ detail: str = ""+ error: str = ""+ warnings: list[str] = field(default_factory=list)+ finished_at: float | None = None+++_lock = threading.Lock()+_run = _Run()+++def setup_snapshot() -> dict[str, Any]:+ with _lock:+ return {+ "running": _run.running, "stage": _run.stage, "progress": round(_run.progress, 3),+ "detail": _run.detail, "error": _run.error, "warnings": list(_run.warnings),+ "finished_at": _run.finished_at,+ }+++def _reset_for_tests() -> None:+ global _run+ with _lock:+ _run = _Run()+++def _progress(stage: str, fraction: float, detail: str = "") -> None:+ done = sum(_STAGE_WEIGHTS[s] for s in SETUP_STAGES[: SETUP_STAGES.index(stage)])+ with _lock:+ _run.stage = stage+ _run.progress = min(1.0, done + _STAGE_WEIGHTS[stage] * max(0.0, min(1.0, fraction)))+ _run.detail = detail+++@dataclass+class SetupDeps:+ """The outside world setup touches; tests hand in fakes (``tests/fakes``)."""++ home: Path+ ensure_uv: Callable[[Path], str]+ run: Callable[[list[str], dict[str, str], int], None]+ fetch_model: Callable[[str, Path, Callable[[str, int, int], None]], None]+ installed_llms: Callable[[], tuple[set[str], str | None]]+ start_ollama: Callable[[], tuple[bool, str]]+ pull_llm: Callable[[str, Callable[[float], None]], None]+ machine: Callable[[], str]+ configured_llm: Callable[[], str]+ configured_voice: Callable[[], str]+ languages: Callable[[], list[str]]+ selftest: Callable[[], dict[str, Any]] | None = None+ package_source: Path = field(+ default_factory=lambda: Path(__file__).resolve().parent.parent / "voice_engine")+++def start_setup(deps: SetupDeps) -> tuple[bool, str]:+ """Start setup in a background thread, or join the one already running."""+ with _lock:+ if _run.running:+ return False, "Setup is already running."+ _run.running = True+ _run.stage, _run.progress, _run.detail, _run.error = SETUP_STAGES[0], 0.0, "", ""+ _run.warnings = []+ _run.finished_at = None+ threading.Thread(target=_run_guarded, args=(deps,), name="local-voice-setup",+ daemon=True).start()+ return True, "Setup started."+++def run_setup_blocking(deps: SetupDeps) -> None:+ """Run setup on the calling thread (tests and the CLI)."""+ with _lock:+ _run.running = True+ _run.error = ""+ _run.warnings = []+ _run_guarded(deps)+++def _run_guarded(deps: SetupDeps) -> None:+ try:+ _run_setup(deps)+ except SetupError as exc:+ log.warning("local voice setup failed at %s: %s", _run.stage, exc)+ with _lock:+ _run.error = str(exc)+ except Exception as exc: # noqa: BLE001 - every failure must reach the card+ log.exception("local voice setup failed at %s", _run.stage)+ with _lock:+ _run.error = f"Setup failed while {_run.stage or 'starting'}: {exc}"+ finally:+ with _lock:+ _run.running = False+ _run.finished_at = time.time()+++def _uv_env(home: Path) -> dict[str, str]:+ env = dict(os.environ)+ # Never install into whatever environment the app itself runs in.+ env.pop("VIRTUAL_ENV", None)+ env.pop("PYTHONPATH", None)+ env.update({+ "UV_PYTHON_INSTALL_DIR": str(home / "python"),+ "UV_CACHE_DIR": str(home / "cache"),+ # A uv-managed CPython, never a store stub or a system build with+ # missing pieces: the engine's interpreter is the same on every OS.+ "UV_PYTHON_PREFERENCE": "only-managed",+ "UV_NO_PROGRESS": "1",+ "PYTHONUTF8": "1",+ })+ return env+++def _engine_python(home: Path) -> Path:+ from jarvis.voice_engine.paths import venv_python # noqa: PLC0415++ return venv_python(home)+++def _models_for(languages: list[str]) -> list[str]:+ from jarvis.voice_engine.models import REGISTRY # noqa: PLC0415++ core = ["silero-vad-v6", "smart-turn-v3.2", "parakeet-tdt-0.6b-v3-int8"]+ piper = [name for lang in languages for name in REGISTRY if name.startswith(f"piper-{lang}-")]+ return core + piper+++def _copy_engine(source: Path, home: Path) -> None:+ """Copy the worker package for builds without an importable source tree."""+ if not (source / "worker.py").is_file():+ raise SetupError("The voice engine's code is missing from this installation.")+ target = home / "app"+ staging = home / "app.new"+ shutil.rmtree(staging, ignore_errors=True)+ shutil.copytree(source, staging / "jarvis" / "voice_engine",+ ignore=shutil.ignore_patterns("__pycache__", "*.pyc"))+ # A bare namespace marker: the worker must never import the app's package.+ (staging / "jarvis" / "__init__.py").write_text("", encoding="utf-8")+ shutil.rmtree(target, ignore_errors=True)+ os.replace(staging, target)+++def _run_setup(deps: SetupDeps) -> None:+ home = deps.home+ home.mkdir(parents=True, exist_ok=True)+ env = _uv_env(home)++ _progress("uv", 0.0, "Getting the Python installer")+ uv = deps.ensure_uv(home / "bin")++ _progress("python", 0.0, f"Creating the engine's Python {_PYTHON_VERSION}")+ python = _engine_python(home)+ if not python.is_file():+ deps.run([uv, "venv", "--python", _PYTHON_VERSION, str(home / "venv")], env,+ _COMMAND_TIMEOUT_S)++ _progress("packages", 0.0, "Installing the speech runtimes")+ deps.run([uv, "pip", "install", "--python", str(python), "--torch-backend", "cpu",+ "-r", str(requirements_file())], env, _COMMAND_TIMEOUT_S)++ _progress("engine", 0.0, "Copying the voice engine")+ _copy_engine(deps.package_source, home)++ languages = deps.languages()+ names = _models_for(languages)+ for index, name in enumerate(names):+ def report(_file: str, done: int, total: int, index: int = index, name: str = name) -> None:+ part = done / total if total else 0.0+ _progress("models", (index + part) / len(names), f"Downloading {name}")++ _progress("models", index / len(names), f"Downloading {name}")+ deps.fetch_model(name, home / "models", report)++ voice = deps.configured_voice()+ _progress("voice", 0.0, f"Preparing the {voice} voice")+ if voice == "pocket":+ prefetch = ("import sys\nfrom jarvis.voice_engine.tts.pocket import PocketTts\n"+ "for language in sys.argv[1:]:\n PocketTts(language)\n")+ voice_env = dict(env)+ voice_env.update({"PYTHONPATH": str(home / "app"), "HF_HOME": str(home / "hf"),+ "HF_HUB_DISABLE_PROGRESS_BARS": "1"})+ try:+ deps.run([str(python), "-c", prefetch, *languages], voice_env, _COMMAND_TIMEOUT_S)+ except SetupError as exc:+ # Degrade, don't die: the engine falls back to Piper per language.+ with _lock:+ _run.warnings.append(+ f"The natural voice could not be prepared ({exc}); calls use Piper instead.")++ _progress("llm", 0.0, "Checking the local language model")+ machine = deps.machine()+ model = deps.configured_llm()+ installed, error = deps.installed_llms()+ if error:+ started, detail = deps.start_ollama()+ if not started:+ raise SetupError(f"The local language model server is not available: {detail}")+ installed, error = deps.installed_llms()+ if error:+ raise SetupError(error)+ if model:+ present = any(_same_tag(model, name) for name in installed)+ else:+ model, present = choose_llm(machine, installed)+ if not present:+ _progress("llm", 0.0, f"Downloading {model}")+ deps.pull_llm(model, lambda pct: _progress("llm", pct / 100.0, f"Downloading {model}"))++ _write_json(home / _SETUP_STATE, {+ "engine_version": engine_version(),+ "requirements_sha256": requirements_sha256(),+ "llm_model": model,+ "tts": voice,+ "machine_class": machine,+ "platform": platform_name(),+ "completed_at": time.time(),+ })+ shutil.rmtree(home / "cache", ignore_errors=True)++ _progress("selftest", 0.0, "Testing the voice")+ if deps.selftest is not None:+ report = deps.selftest()+ if not report.get("ok"):+ raise SetupError(str(report.get("reason") or "The self-test did not pass."))+ _progress("selftest", 1.0, "Done")+++# ---------------------------------------------------------------- self-test+++def selftest_fingerprint(settings: Any) -> dict[str, str]:+ """What a self-test result is bound to; any change makes it stale (plan 4.10)."""+ return {+ "engine_version": engine_version(),+ "requirements_sha256": requirements_sha256(),+ "llm_model": str(getattr(settings, "llm_model", "")),+ "tts": str(getattr(settings, "tts", "")),+ }+++def save_selftest(home: Path, report: dict[str, Any], settings: Any) -> dict[str, Any]:+ record = {"at": time.time(), "fingerprint": selftest_fingerprint(settings),+ "report": report}+ _write_json(home / _SELFTEST_STATE, record)+ return record+++def load_selftest(home: Path, settings: Any) -> dict[str, Any] | None:+ record = _read_json(home / _SELFTEST_STATE)+ report = record.get("report")+ if not isinstance(report, dict):+ return None+ return {+ "ok": bool(report.get("ok")),+ "at": record.get("at"),+ "stale": record.get("fingerprint") != selftest_fingerprint(settings),+ "reason": str(report.get("reason") or ""),+ "languages": report.get("languages") if isinstance(report.get("languages"), dict)+ else {},+ "llm": report.get("llm") if isinstance(report.get("llm"), dict) else None,+ }+++async def run_engine_selftest(engine: Any, *, home: Path, settings: Any) -> dict[str, Any]:+ """Start the engine if needed, wait until it is ready, prove one round trip.++ The result is stored even when it fails, so the card shows the last honest+ verdict instead of a stale success.+ """+ engine.reset_failures()+ try:+ await engine.ensure_started()+ ready = await engine.wait_ready(_SELFTEST_READY_TIMEOUT_S)+ if not ready:+ report = {"ok": False,+ "reason": engine.reason or "The local voice did not finish loading."}+ else:+ report = await engine.selftest()+ except (OSError, RuntimeError, TimeoutError) as exc:+ report = {"ok": False, "reason": f"The self-test could not run: {exc}"}+ save_selftest(home, report, settings)+ return report+++class SelftestRunner:+ """One self-test at a time, on the app's event loop; the card polls status."""++ def __init__(self) -> None:+ self._task: asyncio.Task[dict[str, Any]] | None = None++ @property+ def running(self) -> bool:+ return self._task is not None and not self._task.done()++ def start(self, factory: Callable[[], Awaitable[dict[str, Any]]]) -> bool:+ if self.running:+ return False+ self._task = asyncio.get_running_loop().create_task(factory()) # type: ignore[arg-type]+ return True+++selftests = SelftestRunner()+++def selftest_from_thread(loop: asyncio.AbstractEventLoop,+ factory: Callable[[], Awaitable[dict[str, Any]]],+ timeout_s: float = _SELFTEST_READY_TIMEOUT_S + 150.0) -> dict[str, Any]:+ """Run a self-test coroutine on the app loop from setup's worker thread."""+ future: Future[dict[str, Any]] = asyncio.run_coroutine_threadsafe(factory(), loop) # type: ignore[arg-type]+ return future.result(timeout=timeout_s)+++# ------------------------------------------------------------------ status+++def _live_state(engine: Any) -> tuple[str, str, float, str]:+ """``(phase, stage, progress, reason)`` of the running engine, if any."""+ if engine is None:+ return "stopped", "", 0.0, ""+ if engine._client is None: # noqa: SLF001 - the adapter's own state, read-only+ if engine.phase == "failed":+ return "failed", "", 0.0, engine.reason+ return "stopped", "", 0.0, ""+ if engine.phase == "ready":+ return "ready", "", 1.0, ""+ if engine.phase == "failed":+ return "failed", engine.stage, engine.progress, engine.reason+ return "starting", engine.stage or "process", engine.progress, ""+++def _visible_models(names: Iterable[str]) -> list[str]:+ """Installed tags a user picks from, without Jarvis's own derived aliases."""+ try:+ from jarvis.brain.ollama_inventory import is_hidden_alias # noqa: PLC0415+ except ImportError:+ return sorted(names)+ return sorted(n for n in names if not is_hidden_alias(n))+++async def card_status(+ cfg: Any,+ *,+ installed_llms: Callable[[], Awaitable[tuple[set[str], str | None]]] | None = None,+ machine: str | None = None,+) -> dict[str, Any]:+ """Everything the Local voice card renders, in one payload.++ Reads files, the setup run, the already-running engine and Ollama's tag+ list; it never starts the engine and never downloads anything.+ """+ from jarvis.core.config import VOICE_ENGINE_VOICES # noqa: PLC0415+ from jarvis.plugins.realtime.local_voice import ( # noqa: PLC0415+ NOT_SET_UP_REASON,+ EngineSettings,+ LocalVoiceProvider,+ engine_installed,+ )+ from jarvis.voice_engine.paths import read_setup_state # noqa: PLC0415++ settings = EngineSettings.from_config(cfg)+ home = Path(settings.home) if settings.home else engine_home()+ installed = await asyncio.to_thread(engine_installed, settings)+ run = setup_snapshot()+ if machine is None:+ machine = await asyncio.to_thread(machine_class)+ if installed_llms is None:+ from jarvis.brain.ollama_pull import installed_models # noqa: PLC0415++ installed_llms = installed_models+ names, llm_error = await installed_llms()++ section = getattr(cfg, "voice_engine", None)+ configured = str(getattr(section, "llm_model", "") or "")+ recorded = await asyncio.to_thread(read_setup_state, home)+ if configured:+ llm_model, llm_source = configured, "config"+ elif recorded.get("llm_model"):+ llm_model, llm_source = str(recorded["llm_model"]), "setup"+ else:+ llm_model, _present = choose_llm(machine, names)+ llm_source = "default"+ llm_installed = None if llm_error else any(_same_tag(llm_model, n) for n in names)++ engine = LocalVoiceProvider._engine # noqa: SLF001 - never create one for a status read+ live = engine if engine is not None and engine.settings == settings else None+ if run["running"]:+ phase, stage, progress, reason = "installing", run["stage"], run["progress"], run["detail"]+ elif not installed:+ phase = "failed" if run["error"] else "not_installed"+ stage, progress, reason = "", 0.0, run["error"] or NOT_SET_UP_REASON+ else:+ phase, stage, progress, reason = _live_state(live)+ selftest = await asyncio.to_thread(load_selftest, home, settings)+ platform = platform_name()+ return {+ "phase": phase,+ "stage": stage,+ "progress": round(float(progress), 3),+ "reason": reason,+ "installed": installed,+ "setup": run,+ "llm_model": llm_model,+ "llm_source": llm_source,+ "llm_installed": llm_installed,+ "llm_error": llm_error or "",+ "llm_choices": _visible_models(names),+ "voice": settings.tts,+ "voices": list(VOICE_ENGINE_VOICES),+ "machine_class": machine,+ "expected_latency": expected_latency(machine),+ "platform": platform,+ "os_verified": os_verified(machine, platform),+ "selftest": selftest,+ "selftest_running": selftests.running,+ }+++# ------------------------------------------------------------- real deps+++def _run_command(cmd: list[str], env: dict[str, str], timeout: int) -> None:+ from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS # noqa: PLC0415++ try:+ result = subprocess.run( # noqa: S603 - fixed argv built above, no shell+ cmd, env=env, capture_output=True, text=True, encoding="utf-8",+ errors="replace", timeout=timeout, check=False,+ creationflags=NO_WINDOW_CREATIONFLAGS,+ )+ except (OSError, subprocess.TimeoutExpired) as exc:+ raise SetupError(f"{Path(cmd[0]).name} could not run: {exc}") from exc+ if result.returncode != 0:+ tail = (result.stderr or result.stdout or "").strip().splitlines()[-3:]+ log.warning("local voice setup: %s exited %s: %s", cmd[:3], result.returncode,+ "\n".join(tail))+ raise SetupError(" ".join(tail)[-400:] or f"{Path(cmd[0]).name} failed")+++def _fetch_model(name: str, root: Path, progress: Callable[[str, int, int], None]) -> None:+ from jarvis.voice_engine import models # noqa: PLC0415++ try:+ models.fetch(name, root, progress=progress)+ except (OSError, RuntimeError, ValueError) as exc:+ raise SetupError(f"Downloading {name} failed: {exc}") from exc+++def _installed_llms() -> tuple[set[str], str | None]:+ from jarvis.brain.ollama_pull import installed_models # noqa: PLC0415++ return asyncio.run(installed_models())+++def _start_ollama() -> tuple[bool, str]:+ from jarvis.brain.ollama_runtime import start_server # noqa: PLC0415++ return start_server()+++def _pull_llm(model: str, progress: Callable[[float], None]) -> None:+ """Pull one Ollama model, all inside one event loop (its task lives there)."""++ async def pull() -> None:+ from jarvis.brain.ollama_pull import pull_status, start_pull # noqa: PLC0415++ first = await start_pull(model)+ if str(first.get("state")) == "error":+ raise SetupError(str(first.get("message") or f"Downloading {model} failed."))+ deadline = time.monotonic() + _LLM_PULL_TIMEOUT_S+ while time.monotonic() < deadline:+ status = await pull_status(model)+ state = str(status.get("state"))+ if state == "done":+ return+ if state == "error":+ raise SetupError(str(status.get("error") or status.get("message")+ or f"Downloading {model} failed."))+ progress(float(status.get("percent") or 0.0))+ await asyncio.sleep(2)+ raise SetupError(f"Downloading {model} did not finish within an hour.")++ asyncio.run(pull())+++def _ensure_uv(root: Path) -> str:+ from jarvis.society.browser.bootstrap import ensure_uv # noqa: PLC0415++ try:+ # The pinned uv, never an older one from PATH: setup needs+ # ``--torch-backend`` and managed Python downloads.+ return ensure_uv(root, prefer_path=False)+ except (OSError, RuntimeError, ValueError) as exc:+ raise SetupError(f"The Python installer could not be downloaded: {exc}") from exc+++def real_deps(*, loop: asyncio.AbstractEventLoop | None,+ config_loader: Callable[[], Any]) -> SetupDeps:+ """Setup wired to this machine. ``loop`` runs the closing self-test."""++ def section() -> Any:+ return getattr(config_loader(), "voice_engine", None)++ def selftest() -> dict[str, Any]:+ from jarvis.plugins.realtime.local_voice import ( # noqa: PLC0415+ EngineSettings,+ LocalVoiceProvider,+ )++ cfg = config_loader()+ settings = EngineSettings.from_config(cfg)+ engine = LocalVoiceProvider.shared_engine(cfg)+ home = engine_home()+ if loop is None:+ return {"ok": False, "reason": "No event loop to run the self-test on."}+ return selftest_from_thread(+ loop, lambda: run_engine_selftest(engine, home=home, settings=settings))++ return SetupDeps(+ home=engine_home(),+ ensure_uv=_ensure_uv,+ run=_run_command,+ fetch_model=_fetch_model,+ installed_llms=_installed_llms,+ start_ollama=_start_ollama,+ pull_llm=_pull_llm,+ machine=machine_class,+ configured_llm=lambda: str(getattr(section(), "llm_model", "") or ""),+ configured_voice=lambda: str(getattr(section(), "tts", "") or "pocket"),+ languages=lambda: list(getattr(section(), "languages", None) or ["de", "en"]),+ selftest=selftest,+ )diff --git a/jarvis/society/browser/bootstrap.py b/jarvis/society/browser/bootstrap.pyindex 54dc6153f6..1964255393 100644--- a/jarvis/society/browser/bootstrap.py+++ b/jarvis/society/browser/bootstrap.py@@ -17,8 +17,13 @@ from urllib.parse import urlsplitUV_VERSION = "0.12.9"-def ensure_uv(root: Path) -> str:- found = shutil.which("uv")+def ensure_uv(root: Path, *, prefer_path: bool = True) -> str:+ """A verified ``uv`` binary: from PATH, else downloaded once into ``root``.++ ``prefer_path=False`` skips PATH and uses the pinned :data:`UV_VERSION`, for+ callers that rely on flags an older user-installed uv may lack.+ """+ found = shutil.which("uv") if prefer_path else Noneif found:return foundtarget = root / ("uv.exe" if os.name == "nt" else "uv")diff --git a/jarvis/voice_engine/requirements-engine.txt b/jarvis/voice_engine/requirements-engine.txtnew file mode 100644index 0000000000..4a22825fe4--- /dev/null+++ b/jarvis/voice_engine/requirements-engine.txt@@ -0,0 +1,70 @@+# Pinned package set of the local voice engine's OWN environment (ADR-0037).+#+# Installed by jarvis/realtime/local_voice_setup.py into a uv-managed CPython+# 3.12 venv under the engine home, never into the app's interpreter. Torch is+# fetched with `uv pip install --torch-backend cpu`, so speech runs on the CPU+# everywhere (plan section 4.7) and no 2 GB CUDA wheel is downloaded.+#+# Derived from the P0/P1 measuring environment (Windows x64, CPython 3.12,+# 2026-10-01). Per-platform hashed locks are P3 work (plan section 4.10); until+# then these exact pins are the contract. Only Windows x64 was installed from+# this list so far; macOS and Linux resolve from the same pins unverified.++# --- direct dependencies of jarvis/voice_engine ---+numpy==2.5.3+onnxruntime==1.30.0+sherpa-onnx==1.13.8+sherpa-onnx-core==1.13.8+soxr==1.1.0+pocket-tts==3.3.0+torch==2.14.1++# --- transitive pins (pocket-tts, torch, onnxruntime, huggingface-hub) ---+annotated-doc==0.0.5+annotated-types==0.8.0+anyio==4.15.1+certifi==2026.7.22+charset-normalizer==3.5.2+click==8.5.0+colorama==0.4.6 ; sys_platform == "win32"+einops==0.8.2+fastapi==0.142.2+filelock==4.0.8+flatbuffers==25.12.19+fsspec==2026.9.0+h11==0.16.0+hf-xet==1.6.0+httpcore==1.0.9+httpx==0.28.1+huggingface-hub==1.33.0+idna==3.20+jinja2==3.1.6+markdown-it-py==4.2.0+markupsafe==3.0.3+mdurl==0.1.2+mpmath==1.3.0+networkx==3.7+opentelemetry-api==1.45.0+packaging==26.3+protobuf==7.36.2+pydantic==2.13.5+pydantic-core==2.46.5+pygments==2.21.0+python-multipart==0.0.32+pyyaml==6.0.3+requests==2.34.2+rich==15.0.0+safetensors==0.8.0+scipy==1.18.1+sentencepiece==0.2.2+setuptools==84.0.0+shellingham==1.5.4+starlette==1.7.0+sympy==1.14.0+tokenizers==0.23.2+tqdm==4.70.1+typer==0.27.2+typing-extensions==4.16.0+typing-inspection==0.4.4+urllib3==2.8.0+uvicorn==0.54.0diff --git a/tests/fakes/fake_voice_engine_setup.py b/tests/fakes/fake_voice_engine_setup.pynew file mode 100644index 0000000000..aabf3a6b7e--- /dev/null+++ b/tests/fakes/fake_voice_engine_setup.py@@ -0,0 +1,102 @@+"""A fake machine for the local voice setup (``jarvis/realtime/local_voice_setup.py``).++Records every command, download and pull, and leaves the same files behind the+real steps would (the venv interpreter, the model directories), so setup and+the status read can be driven end to end in a temporary engine home without+uv, the network or Ollama.+"""++from __future__ import annotations++from collections.abc import Callable+from dataclasses import dataclass, field+from pathlib import Path+from typing import Any++from jarvis.realtime.local_voice_setup import SetupDeps, SetupError+from jarvis.voice_engine import models+from jarvis.voice_engine.paths import venv_python+++@dataclass+class FakeSetupWorld:+ home: Path+ machine_class: str = "nvidia"+ installed: set[str] = field(default_factory=set)+ ollama_running: bool = True+ ollama_installed: bool = True+ configured_llm: str = ""+ voice: str = "pocket"+ languages: list[str] = field(default_factory=lambda: ["de", "en"])+ fail_command: str = ""+ selftest_report: dict[str, Any] | None = field(default_factory=lambda: {"ok": True})+ commands: list[list[str]] = field(default_factory=list)+ envs: list[dict[str, str]] = field(default_factory=list)+ fetched: list[str] = field(default_factory=list)+ pulled: list[str] = field(default_factory=list)+ ollama_starts: int = 0++ def ensure_uv(self, root: Path) -> str:+ root.mkdir(parents=True, exist_ok=True)+ return str(root / "uv")++ def run(self, cmd: list[str], env: dict[str, str], timeout: int) -> None:+ del timeout+ self.commands.append(list(cmd))+ self.envs.append(dict(env))+ if self.fail_command and self.fail_command in " ".join(cmd):+ raise SetupError(f"fake failure in {self.fail_command}")+ if cmd[1:2] == ["venv"]:+ python = venv_python(self.home)+ python.parent.mkdir(parents=True, exist_ok=True)+ python.write_text("", encoding="utf-8")++ def fetch_model(self, name: str, root: Path,+ progress: Callable[[str, int, int], None]) -> None:+ self.fetched.append(name)+ progress(name, 1, 2)+ path = models.model_path(name, root)+ if models.REGISTRY[name].is_archive:+ path.mkdir(parents=True, exist_ok=True)+ (path / "model.onnx").write_bytes(b"x")+ else:+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_bytes(b"x")+ progress(name, 2, 2)++ def installed_llms(self) -> tuple[set[str], str | None]:+ if not self.ollama_running:+ return set(), "Ollama did not answer."+ return set(self.installed), None++ def start_ollama(self) -> tuple[bool, str]:+ self.ollama_starts += 1+ if not self.ollama_installed:+ return False, "Ollama is not installed — install it first."+ self.ollama_running = True+ return True, "started"++ def pull_llm(self, model: str, progress: Callable[[float], None]) -> None:+ self.pulled.append(model)+ progress(50.0)+ self.installed.add(model)++ def selftest(self) -> dict[str, Any]:+ return dict(self.selftest_report or {})++ def deps(self, package_source: Path) -> SetupDeps:+ return SetupDeps(+ home=self.home,+ ensure_uv=self.ensure_uv,+ run=self.run,+ fetch_model=self.fetch_model,+ installed_llms=self.installed_llms,+ start_ollama=self.start_ollama,+ pull_llm=self.pull_llm,+ machine=lambda: self.machine_class,+ configured_llm=lambda: self.configured_llm,+ configured_voice=lambda: self.voice,+ languages=lambda: list(self.languages),+ selftest=self.selftest if self.selftest_report is not None else None,+ package_source=package_source,+ )diff --git a/tests/unit/voice_engine/test_local_voice_setup.py b/tests/unit/voice_engine/test_local_voice_setup.pynew file mode 100644index 0000000000..637618a922--- /dev/null+++ b/tests/unit/voice_engine/test_local_voice_setup.py@@ -0,0 +1,198 @@+"""Local voice setup: the steps, the installed-first model choice, the card status."""++from __future__ import annotations++import asyncio+import json+from pathlib import Path+from types import SimpleNamespace++import pytest++from jarvis.core.config import JarvisConfig, VoiceEngineConfig+from jarvis.plugins.realtime.local_voice import LocalVoiceProvider+from jarvis.realtime import local_voice_setup as setup+from jarvis.voice_engine.paths import read_setup_state, venv_python+from tests.fakes.fake_voice_engine_setup import FakeSetupWorld++PACKAGE = Path(setup.__file__).resolve().parent.parent / "voice_engine"++[email protected](autouse=True)+def _isolated_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ home = tmp_path / "engine"+ monkeypatch.setenv("JARVIS_VOICE_ENGINE_HOME", str(home))+ setup._reset_for_tests()+ LocalVoiceProvider._engine = None+ yield home+ setup._reset_for_tests()+ LocalVoiceProvider._engine = None+++def _world(home: Path, **kwargs) -> FakeSetupWorld:+ return FakeSetupWorld(home=home, **kwargs)+++def test_setup_builds_the_environment_and_records_the_choice(_isolated_home: Path) -> None:+ world = _world(_isolated_home, installed={"qwen3.5:4b"})+ setup.run_setup_blocking(world.deps(PACKAGE))++ snapshot = setup.setup_snapshot()+ assert snapshot["error"] == "" and snapshot["running"] is False+ assert snapshot["progress"] == pytest.approx(1.0)+ venv, install, prefetch = world.commands+ assert venv[1:4] == ["venv", "--python", "3.12"]+ assert install[1:3] == ["pip", "install"]+ assert ["--torch-backend", "cpu"] == install[install.index("--torch-backend"):][:2]+ assert install[-1].endswith("requirements-engine.txt")+ assert prefetch[0] == str(venv_python(_isolated_home)) and prefetch[-2:] == ["de", "en"]+ # uv never installs into the app's own environment and keeps its Python home-local.+ assert "VIRTUAL_ENV" not in world.envs[1]+ assert world.envs[0]["UV_PYTHON_PREFERENCE"] == "only-managed"+ assert world.envs[2]["HF_HOME"] == str(_isolated_home / "hf")+ assert world.fetched[:3] == ["silero-vad-v6", "smart-turn-v3.2", "parakeet-tdt-0.6b-v3-int8"]+ assert {"piper-de-thorsten-medium", "piper-en-ryan-medium"} <= set(world.fetched)+ assert (_isolated_home / "app" / "jarvis" / "voice_engine" / "worker.py").is_file()+ assert (_isolated_home / "app" / "jarvis" / "__init__.py").read_text(encoding="utf-8") == ""+ assert world.pulled == [] # installed first: nothing to download+ state = read_setup_state(_isolated_home)+ assert state["llm_model"] == "qwen3.5:4b" and state["tts"] == "pocket"+ assert state["requirements_sha256"] == setup.requirements_sha256()+++def test_a_cpu_machine_pulls_the_small_default_when_nothing_fits(_isolated_home: Path) -> None:+ world = _world(_isolated_home, machine_class="cpu", installed={"llama3.2:3b"})+ setup.run_setup_blocking(world.deps(PACKAGE))+ assert world.pulled == ["qwen3.5:2b"]+ assert read_setup_state(_isolated_home)["llm_model"] == "qwen3.5:2b"+++def test_setup_starts_ollama_once_and_fails_honestly_without_it(_isolated_home: Path) -> None:+ world = _world(_isolated_home, ollama_running=False, ollama_installed=False)+ setup.run_setup_blocking(world.deps(PACKAGE))+ snapshot = setup.setup_snapshot()+ assert world.ollama_starts == 1+ assert "not installed" in snapshot["error"]+ assert snapshot["stage"] == "llm"+ # The speech half stays installed; only the language model is missing.+ assert venv_python(_isolated_home).is_file()+++def test_a_failed_voice_prefetch_degrades_to_piper(_isolated_home: Path) -> None:+ world = _world(_isolated_home, installed={"qwen3.5:4b"}, fail_command="PocketTts")+ setup.run_setup_blocking(world.deps(PACKAGE))+ snapshot = setup.setup_snapshot()+ assert snapshot["error"] == ""+ assert snapshot["warnings"] and "Piper" in snapshot["warnings"][0]+++def test_a_failed_selftest_fails_setup_with_its_reason(_isolated_home: Path) -> None:+ world = _world(_isolated_home, installed={"qwen3.5:4b"},+ selftest_report={"ok": False, "reason": "The voice could not hear itself."})+ setup.run_setup_blocking(world.deps(PACKAGE))+ assert setup.setup_snapshot()["error"] == "The voice could not hear itself."+++def test_a_package_failure_stops_setup_at_that_stage(_isolated_home: Path) -> None:+ world = _world(_isolated_home, fail_command="requirements-engine.txt")+ setup.run_setup_blocking(world.deps(PACKAGE))+ snapshot = setup.setup_snapshot()+ assert snapshot["stage"] == "packages" and "fake failure" in snapshot["error"]+ assert world.fetched == []+++def test_requirements_pin_every_package_exactly() -> None:+ lines = [+ line.split(";")[0].strip()+ for line in setup.requirements_file().read_text(encoding="utf-8").splitlines()+ if line.strip() and not line.startswith("#")+ ]+ assert lines and all("==" in line for line in lines)+ names = {line.split("==")[0].lower() for line in lines}+ assert {"numpy", "onnxruntime", "sherpa-onnx", "pocket-tts", "torch"} <= names+++ ("probe", "expected"),+ [+ ((16.0, "nvidia-smi"), "nvidia"),+ ((16.0, "apple-unified"), "apple"),+ ((8.0, "linux-drm"), "gpu"),+ ((4.0, "nvidia-smi"), "cpu"),+ ((0.0, "none"), "cpu"),+ ],+)+def test_machine_class_reads_the_shared_probe(probe, expected) -> None:+ assert setup.machine_class(lambda: probe) == expected+++def test_a_broken_probe_reads_as_cpu() -> None:+ def broken() -> tuple[float, str]:+ raise OSError("nvidia-smi hung")++ assert setup.machine_class(broken) == "cpu"+++def test_installed_models_win_over_the_default() -> None:+ assert setup.choose_llm("nvidia", {"granite4.2:8b", "x:1b"}) == ("granite4.2:8b", True)+ # A different size of the same family is not the measured model.+ assert setup.choose_llm("nvidia", {"qwen3.5:latest", "qwen3.5:9b"}) == ("qwen3.5:4b", False)+ assert setup.choose_llm("nvidia", set()) == ("qwen3.5:4b", False)+ assert setup.choose_llm("cpu", {"qwen3.5:4b"}) == ("qwen3.5:4b", True)+ assert setup.choose_llm("cpu", set()) == ("qwen3.5:2b", False)+++def test_only_measured_platforms_count_as_verified() -> None:+ assert setup.os_verified("nvidia", "windows")+ assert setup.os_verified("cpu", "linux")+ assert not setup.os_verified("apple", "macos")+ assert not setup.os_verified("nvidia", "linux")+ assert setup.expected_latency("nvidia")["basis"] == "measured"+ assert setup.expected_latency("gpu") == {"low_s": None, "high_s": None, "basis": "selftest"}+++def _status(cfg, *, installed=frozenset(), error=None, machine="nvidia"):+ async def llms():+ return set(installed), error++ return asyncio.run(setup.card_status(cfg, installed_llms=llms, machine=machine))+++def test_status_before_setup_names_the_next_step(_isolated_home: Path) -> None:+ status = _status(JarvisConfig(), installed={"qwen3.5:4b"})+ assert status["phase"] == "not_installed" and status["installed"] is False+ assert "setup" in status["reason"]+ assert status["llm_model"] == "qwen3.5:4b" and status["llm_source"] == "default"+ assert status["llm_installed"] is True+ assert status["voice"] == "pocket" and status["voices"] == ["pocket", "piper"]+ assert status["selftest"] is None and status["selftest_running"] is False+ assert set(status) >= {"expected_latency", "os_verified", "platform", "machine_class"}+++def test_status_after_setup_is_stopped_with_the_recorded_model(_isolated_home: Path) -> None:+ world = _world(_isolated_home, installed={"granite4.2:8b"})+ setup.run_setup_blocking(world.deps(PACKAGE))+ status = _status(JarvisConfig(), installed={"granite4.2:8b"})+ assert status["installed"] is True and status["phase"] == "stopped"+ assert (status["llm_model"], status["llm_source"]) == ("granite4.2:8b", "setup")+++def test_an_explicit_card_pick_wins_and_ollama_errors_stay_visible(_isolated_home: Path) -> None:+ cfg = JarvisConfig(voice_engine=VoiceEngineConfig(llm_model="gemma4:12b-it-qat", tts="piper"))+ status = _status(cfg, error="Ollama did not answer.")+ assert (status["llm_model"], status["llm_source"]) == ("gemma4:12b-it-qat", "config")+ assert status["llm_installed"] is None and status["llm_error"] == "Ollama did not answer."+ assert status["voice"] == "piper"+++def test_a_stored_selftest_goes_stale_when_the_model_changes(_isolated_home: Path) -> None:+ settings = SimpleNamespace(llm_model="qwen3.5:4b", tts="pocket")+ setup.save_selftest(_isolated_home, {"ok": True, "languages": {"de": {"ok": True}},+ "llm": {"ok": True, "ms": 390}}, settings)+ fresh = setup.load_selftest(_isolated_home, settings)+ assert fresh["ok"] is True and fresh["stale"] is False and fresh["llm"]["ms"] == 390+ moved = setup.load_selftest(_isolated_home, SimpleNamespace(llm_model="qwen3.5:2b",+ tts="pocket"))+ assert moved["stale"] is True+ raw = json.loads((_isolated_home / "selftest.json").read_text(encoding="utf-8"))+ assert raw["fingerprint"]["engine_version"] == setup.engine_version()