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.

feat(ui): local voice card routes for status, setup, self-test and settings

rubenluetke10-beepdc7ea8887f6d
diff --git a/jarvis/ui/web/local_voice_routes.py b/jarvis/ui/web/local_voice_routes.py
new file mode 100644
index 0000000000..2a08c652de
--- /dev/null
+++ b/jarvis/ui/web/local_voice_routes.py
@@ -0,0 +1,126 @@
+"""Local voice card: status, one-click setup, self-test and settings (ADR-0037).
+
+The card talks only to these routes. Nothing here runs on its own: setup and
+the self-test start when the user presses the card's buttons, and the status
+read never starts the engine or downloads anything (AP-26; nothing the user
+did not start may run or bill anything).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel
+
+from jarvis.core import config as cfg_mod
+
+log = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/providers/local-voice", tags=["providers"])
+
+
+class LocalVoiceSettingsBody(BaseModel):
+ """A partial update: an omitted field keeps its value."""
+
+ voice: str | None = None
+ #: An Ollama tag; an empty string returns to the automatic choice.
+ llm_model: str | None = None
+
+
+def _config(request: Request) -> Any:
+ """The app's live configuration object, the one live calls also read."""
+ cfg = getattr(request.app.state, "config", None) or getattr(request.app.state, "cfg", None)
+ if cfg is not None:
+ return cfg
+ try:
+ return cfg_mod.load_config()
+ except Exception as exc: # noqa: BLE001 - the card degrades to defaults
+ log.warning("Local voice routes could not load the configuration (%s: %s); "
+ "the card shows defaults", type(exc).__name__, exc)
+ return None
+
+
[email protected]("/status", summary="Local voice engine status for the settings card")
+async def local_voice_status(request: Request) -> dict[str, Any]:
+ """Phase, setup progress, chosen model and voice, expected latency, self-test."""
+ from jarvis.realtime.local_voice_setup import card_status # noqa: PLC0415
+
+ return await card_status(_config(request))
+
+
[email protected]("/setup", summary="Start (or join) the local voice engine setup")
+async def local_voice_setup(request: Request) -> dict[str, Any]:
+ """Build the engine's environment, fetch its models and prove it works.
+
+ Returns at once; the work runs in a background thread and the card polls
+ ``/status``. A second call while setup runs joins it.
+ """
+ from jarvis.realtime.local_voice_setup import ( # noqa: PLC0415
+ card_status,
+ real_deps,
+ start_setup,
+ )
+
+ cfg = _config(request)
+ deps = real_deps(loop=asyncio.get_running_loop(), config_loader=lambda: _config(request))
+ started, message = start_setup(deps)
+ payload = await card_status(cfg)
+ payload.update({"started": started, "message": message})
+ return payload
+
+
[email protected]("/selftest", summary="Run the local voice self-test")
+async def local_voice_selftest(request: Request) -> dict[str, Any]:
+ """Start the engine if needed and speak, hear and answer once per language."""
+ from jarvis.plugins.realtime.local_voice import ( # noqa: PLC0415
+ NOT_SET_UP_REASON,
+ EngineSettings,
+ LocalVoiceProvider,
+ engine_installed,
+ )
+ from jarvis.realtime.local_voice_setup import ( # noqa: PLC0415
+ card_status,
+ engine_home,
+ run_engine_selftest,
+ selftests,
+ )
+
+ cfg = _config(request)
+ settings = EngineSettings.from_config(cfg)
+ if not await asyncio.to_thread(engine_installed, settings):
+ raise HTTPException(status_code=409, detail=NOT_SET_UP_REASON)
+ engine = LocalVoiceProvider.shared_engine(cfg)
+ home = engine_home()
+ started = selftests.start(lambda: run_engine_selftest(engine, home=home, settings=settings))
+ payload = await card_status(cfg)
+ payload["started"] = started
+ return payload
+
+
[email protected]("/settings", summary="Choose the local voice and language model")
+async def local_voice_settings(request: Request, body: LocalVoiceSettingsBody) -> dict[str, Any]:
+ """Persist the card's choices to ``[voice_engine]`` and apply them in memory.
+
+ The next engine start uses them; a running engine is replaced on the next
+ call or self-test, never mid-call.
+ """
+ from jarvis.core import config_writer # noqa: PLC0415
+ from jarvis.realtime.local_voice_setup import card_status # noqa: PLC0415
+
+ try:
+ await asyncio.to_thread(
+ config_writer.set_voice_engine_settings, tts=body.voice, llm_model=body.llm_model
+ )
+ except ValueError as exc:
+ raise HTTPException(status_code=400, detail=str(exc)) from exc
+ cfg = _config(request)
+ section = getattr(cfg, "voice_engine", None)
+ if section is not None:
+ if body.voice is not None:
+ section.tts = body.voice.strip().lower()
+ if body.llm_model is not None:
+ section.llm_model = body.llm_model.strip()
+ return await card_status(cfg)
diff --git a/jarvis/ui/web/provider_routes.py b/jarvis/ui/web/provider_routes.py
index 5b4cb1bf48..6c1487740a 100644
--- a/jarvis/ui/web/provider_routes.py
+++ b/jarvis/ui/web/provider_routes.py
@@ -462,6 +462,36 @@ def _managed_server_payload(spec: ProviderSpec) -> dict[str, Any] | None:
return None
+def _voice_engine_payload(spec: ProviderSpec) -> dict[str, Any] | None:
+ """Installed/ready of the Jarvis-owned local voice engine; None elsewhere.
+
+ Only the Local voice card carries it. File checks and the running engine's
+ state only: the full card status (models, latency, self-test) lives at
+ ``GET /api/providers/local-voice/status``.
+ """
+ if spec.id != "local-voice":
+ return None
+ try:
+ from jarvis.plugins.realtime.local_voice import (
+ EngineSettings,
+ LocalVoiceProvider,
+ engine_installed,
+ )
+
+ settings = EngineSettings.from_config(None)
+ engine = LocalVoiceProvider._engine
+ ready = bool(
+ engine is not None
+ and engine.settings == settings
+ and engine.phase == "ready"
+ and engine._client is not None
+ )
+ return {"installed": engine_installed(settings), "ready": ready}
+ except Exception as exc: # noqa: BLE001 — the provider list must never 500
+ log.debug("Local voice probe failed (%s); reporting none.", exc)
+ return None
+
+
def _derived_alias_free(provider_id: str, models: list[Any]) -> list[Any]:
"""Drop the runtime's OWN derived models from a user-facing picker.
@@ -695,6 +725,9 @@ def _spec_to_payload(
# Self-hosted realtime card only: state of the one-click managed
# server install (fail-closed, server sentence rendered verbatim).
"managed_server": _managed_server_payload(spec),
+ # Local voice card only: whether the engine is set up and running.
+ # The card fetches its full status from /api/providers/local-voice.
+ "voice_engine": _voice_engine_payload(spec),
# Gemini's AI-Studio-vs-Vertex split; None for single-path providers.
"alt_credential": (
{
diff --git a/jarvis/ui/web/server.py b/jarvis/ui/web/server.py
index 28b06a635f..a732561c40 100644
--- a/jarvis/ui/web/server.py
+++ b/jarvis/ui/web/server.py
@@ -364,6 +364,7 @@ class WebServer:
from .frontier_routes import router as frontier_router
from .grok_build_routes import router as grok_build_router
from .live_routes import router as live_router
+ from .local_voice_routes import router as local_voice_router
from .local_models_assistant_routes import (
router as local_models_assistant_router,
)
@@ -444,6 +445,8 @@ class WebServer:
# cancellation busy-loop from inside the loop; see diagnostics_routes.
app.include_router(diagnostics_router)
app.include_router(provider_router)
+ # Local voice card (setup, status, self-test) — ADR-0037.
+ app.include_router(local_voice_router)
app.include_router(live_router)
from jarvis.agent_chat.tasks import run_subscription_task
from jarvis.core.task_agent import register_runner
diff --git a/tests/unit/ui/web/test_local_voice_routes.py b/tests/unit/ui/web/test_local_voice_routes.py
new file mode 100644
index 0000000000..81a9d916f8
--- /dev/null
+++ b/tests/unit/ui/web/test_local_voice_routes.py
@@ -0,0 +1,114 @@
+"""Routes behind the Local voice card (``jarvis/ui/web/local_voice_routes.py``).
+
+Pins: the status read never starts anything, the self-test refuses honestly
+before setup, settings land in ``[voice_engine]`` through the config writer and
+in memory, and the provider list carries the card's ``voice_engine`` probe.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from jarvis.brain import ollama_pull
+from jarvis.core import config_writer
+from jarvis.core.bus import EventBus
+from jarvis.core.config import JarvisConfig
+from jarvis.plugins.realtime.local_voice import LocalVoiceProvider
+from jarvis.realtime import local_voice_setup as setup
+from jarvis.ui.web.local_voice_routes import router
+
+
+def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ engine_home = tmp_path / "engine"
+ monkeypatch.setenv("JARVIS_VOICE_ENGINE_HOME", str(engine_home))
+ monkeypatch.setattr(setup, "machine_class", lambda probe=None: "cpu")
+
+ async def installed() -> tuple[set[str], str | None]:
+ return {"qwen3.5:2b"}, None
+
+ monkeypatch.setattr(ollama_pull, "installed_models", installed)
+ setup._reset_for_tests()
+ LocalVoiceProvider._engine = None
+ yield engine_home
+ setup._reset_for_tests()
+ LocalVoiceProvider._engine = None
+
+
+def client(home: Path) -> TestClient:
+ app = FastAPI()
+ app.include_router(router)
+ app.state.config = JarvisConfig()
+ return TestClient(app)
+
+
+def test_status_before_setup_starts_nothing(client: TestClient, home: Path) -> None:
+ resp = client.get("/api/providers/local-voice/status")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["phase"] == "not_installed"
+ assert body["machine_class"] == "cpu"
+ assert (body["llm_model"], body["llm_installed"]) == ("qwen3.5:2b", True)
+ assert body["expected_latency"]["basis"] == "estimate"
+ assert LocalVoiceProvider._engine is None
+ assert not home.exists()
+
+
+def test_selftest_refuses_before_setup(client: TestClient) -> None:
+ resp = client.post("/api/providers/local-voice/selftest")
+ assert resp.status_code == 409
+ assert "not set up" in resp.json()["detail"]
+
+
+def test_settings_are_written_and_applied(client: TestClient, tmp_path: Path) -> None:
+ config_file = tmp_path / "jarvis.toml"
+ config_file.write_text("[brain]\nprimary = \"ollama\"\n", encoding="utf-8")
+ original = config_writer.set_voice_engine_settings
+
+ def write_here(**kwargs):
+ return original(path=config_file, **kwargs)
+
+ pytest.MonkeyPatch().setattr(config_writer, "set_voice_engine_settings", write_here)
+ try:
+ resp = client.put("/api/providers/local-voice/settings",
+ json={"voice": "piper", "llm_model": "granite4.2:8b"})
+ finally:
+ config_writer.set_voice_engine_settings = original
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["voice"] == "piper"
+ assert (body["llm_model"], body["llm_source"]) == ("granite4.2:8b", "config")
+ text = config_file.read_text(encoding="utf-8")
+ assert "[voice_engine]" in text and 'tts = "piper"' in text
+ assert 'llm_model = "granite4.2:8b"' in text
+
+
+def test_an_unknown_voice_is_rejected(client: TestClient) -> None:
+ resp = client.put("/api/providers/local-voice/settings", json={"voice": "kokoro"})
+ assert resp.status_code == 400
+
+
+def test_the_provider_list_carries_the_voice_engine_probe(
+ home: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ from jarvis.ui.web.server import WebServer
+
+ monkeypatch.setenv("JARVIS_DATA_DIR", str(tmp_path))
+ cfg = JarvisConfig()
+ cfg.ui.dev_mode = True
+ srv = WebServer(cfg, bus=EventBus())
+ srv.app.state.config = cfg
+ with TestClient(srv.app) as web:
+ resp = web.get("/api/providers")
+ assert resp.status_code == 200
+ payload = resp.json()
+ rows = payload["providers"] if isinstance(payload, dict) else payload
+ providers = {row["id"]: row for row in rows}
+ assert providers["local-voice"]["voice_engine"] == {"installed": False, "ready": False}
+ assert providers["local-voice"]["billing"] == "local"
+ assert providers["gemini-live"]["voice_engine"] is None