python-voiceio 1.1.0__tar.gz → 1.2.0__tar.gz

{python_voiceio-1.1.0/python_voiceio.egg-info → python_voiceio-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.1.0
+Version: 1.2.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -292,7 +292,7 @@ There is a best-effort pynput path for both (hotkeys and typing, no live preview
 | Hotkey does nothing on Wayland | `voiceio doctor --fix` installs the keyboard udev rule, or bind `voiceio toggle` in your compositor |
 | `sounddevice is not installed` | You installed without the desktop extra: `pipx install --force 'python-voiceio[desktop]'` |
 | evdev fails to build | Install a C toolchain and Python headers (see Quickstart), then reinstall |
-| Too slow | `voiceio doctor` shows your real stop→text; turn off cloud postcorrect, or `voiceio models use small` (or a GPU with `large-v3-turbo`) |
+| Too slow | `voiceio doctor` shows your real stop→text. Turn off cloud postcorrect; use `voiceio models use small` (or a GPU with `large-v3-turbo`); or narrow the beam of the passes you keep: on the author's 44 clips `[model] beam_size = 2` matched the default 5 (WER 4.9% vs 5.4%, vocabulary 28/32 vs 29/32) while decoding faster; greedy (`1`) lost vocabulary (26/32). Measure on yours: `voiceio learn eval --beam 2` |
 | Words come out wrong in a pattern | `voiceio learn eval --pipeline` and `voiceio corrections audit` show which stage or rule did it |
 | Start over | `voiceio uninstall`, then `voiceio setup` |
 
@@ -300,7 +300,7 @@ Logs: `journalctl --user -u voiceio` or `~/.local/state/voiceio/voiceio.log`.
 
 ## Roadmap
 
-- **A landing page** — voiceio as local, open-source, private dictation that learns from you.
+- **A landing page** — voiceio as local, open-source, private dictation that learns from you. A draft is in [`site/index.html`](site/index.html), ready for GitHub Pages.
 - **Hands-off promotion** — `learn schedule` already retrains nightly and tells you when a model wins; next is switching to it automatically, with one-command rollback.
 - **Unbounded vocabulary** — move to a decoder whose biasing has no token cap (see [model choice](CONTRIBUTING.md#model-choice-why-whisper-and-what-would-change-it)).
 - **One model everywhere** — sync your fine-tune to your phone server and laptops, peer to peer.

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/README.md

@@ -239,7 +239,7 @@ There is a best-effort pynput path for both (hotkeys and typing, no live preview
 | Hotkey does nothing on Wayland | `voiceio doctor --fix` installs the keyboard udev rule, or bind `voiceio toggle` in your compositor |
 | `sounddevice is not installed` | You installed without the desktop extra: `pipx install --force 'python-voiceio[desktop]'` |
 | evdev fails to build | Install a C toolchain and Python headers (see Quickstart), then reinstall |
-| Too slow | `voiceio doctor` shows your real stop→text; turn off cloud postcorrect, or `voiceio models use small` (or a GPU with `large-v3-turbo`) |
+| Too slow | `voiceio doctor` shows your real stop→text. Turn off cloud postcorrect; use `voiceio models use small` (or a GPU with `large-v3-turbo`); or narrow the beam of the passes you keep: on the author's 44 clips `[model] beam_size = 2` matched the default 5 (WER 4.9% vs 5.4%, vocabulary 28/32 vs 29/32) while decoding faster; greedy (`1`) lost vocabulary (26/32). Measure on yours: `voiceio learn eval --beam 2` |
 | Words come out wrong in a pattern | `voiceio learn eval --pipeline` and `voiceio corrections audit` show which stage or rule did it |
 | Start over | `voiceio uninstall`, then `voiceio setup` |
 
@@ -247,7 +247,7 @@ Logs: `journalctl --user -u voiceio` or `~/.local/state/voiceio/voiceio.log`.
 
 ## Roadmap
 
-- **A landing page** — voiceio as local, open-source, private dictation that learns from you.
+- **A landing page** — voiceio as local, open-source, private dictation that learns from you. A draft is in [`site/index.html`](site/index.html), ready for GitHub Pages.
 - **Hands-off promotion** — `learn schedule` already retrains nightly and tells you when a model wins; next is switching to it automatically, with one-command rollback.
 - **Unbounded vocabulary** — move to a decoder whose biasing has no token cap (see [model choice](CONTRIBUTING.md#model-choice-why-whisper-and-what-would-change-it)).
 - **One model everywhere** — sync your fine-tune to your phone server and laptops, peer to peer.

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-voiceio"
-version = "1.1.0"
+version = "1.2.0"
 description = "Voice dictation for Linux. Speak → text, locally, instantly."
 readme = "README.md"
 license = "MIT"

{python_voiceio-1.1.0 → python_voiceio-1.2.0/python_voiceio.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.1.0
+Version: 1.2.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -292,7 +292,7 @@ There is a best-effort pynput path for both (hotkeys and typing, no live preview
 | Hotkey does nothing on Wayland | `voiceio doctor --fix` installs the keyboard udev rule, or bind `voiceio toggle` in your compositor |
 | `sounddevice is not installed` | You installed without the desktop extra: `pipx install --force 'python-voiceio[desktop]'` |
 | evdev fails to build | Install a C toolchain and Python headers (see Quickstart), then reinstall |
-| Too slow | `voiceio doctor` shows your real stop→text; turn off cloud postcorrect, or `voiceio models use small` (or a GPU with `large-v3-turbo`) |
+| Too slow | `voiceio doctor` shows your real stop→text. Turn off cloud postcorrect; use `voiceio models use small` (or a GPU with `large-v3-turbo`); or narrow the beam of the passes you keep: on the author's 44 clips `[model] beam_size = 2` matched the default 5 (WER 4.9% vs 5.4%, vocabulary 28/32 vs 29/32) while decoding faster; greedy (`1`) lost vocabulary (26/32). Measure on yours: `voiceio learn eval --beam 2` |
 | Words come out wrong in a pattern | `voiceio learn eval --pipeline` and `voiceio corrections audit` show which stage or rule did it |
 | Start over | `voiceio uninstall`, then `voiceio setup` |
 
@@ -300,7 +300,7 @@ Logs: `journalctl --user -u voiceio` or `~/.local/state/voiceio/voiceio.log`.
 
 ## Roadmap
 
-- **A landing page** — voiceio as local, open-source, private dictation that learns from you.
+- **A landing page** — voiceio as local, open-source, private dictation that learns from you. A draft is in [`site/index.html`](site/index.html), ready for GitHub Pages.
 - **Hands-off promotion** — `learn schedule` already retrains nightly and tells you when a model wins; next is switching to it automatically, with one-command rollback.
 - **Unbounded vocabulary** — move to a decoder whose biasing has no token cap (see [model choice](CONTRIBUTING.md#model-choice-why-whisper-and-what-would-change-it)).
 - **One model everywhere** — sync your fine-tune to your phone server and laptops, peer to peer.

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/tests/test_health.py

@@ -105,3 +105,21 @@ def test_usage_decoder_counts_incidents_on_the_current_release(tmp_path, monkeyp
     assert ok
     assert finding.startswith(f"decoder: 0 hangs, 1 crashes in the last 7 days on {__version__}")
     assert f"(1 more before {__version__})" in finding
+
+
+def test_learning_status_and_tips(monkeypatch):
+    from voiceio import config, service
+    from voiceio.health import _accuracy_tips, _learning_status
+    from voiceio.learn.store import learn_dir
+    monkeypatch.setattr(service, "learn_timer_enabled", lambda: False)
+    cfg = config.Config()
+    st = _learning_status(cfg)
+    assert st["Voice model"] == "stock (small)" and st["Recordings"].startswith("off")
+    assert any("retain_audio true" in t for t in _accuracy_tips(st))
+
+    cfg.data.retain_audio = True
+    cfg.model.name = str(learn_dir() / "models" / "v0001-small-x" / "ct2")
+    st = _learning_status(cfg)
+    assert st["Voice model"] == "fine-tuned on you (v0001-small-x)"
+    assert st["Recordings"].startswith("on (") and st["Nightly learning"] == "off"
+    assert any("learn schedule on" in t for t in _accuracy_tips(st))

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/tests/test_learn_pipeline.py

@@ -230,11 +230,27 @@ def test_maintain_waits_for_enough_new_clips(monkeypatch, capsys):
     store.add_label("new.wav", [Segment(0, 3, "a new one")], "teacher:fake")
 
     monkeypatch.setattr(cli, "cmd_label", lambda args: None)
+    monkeypatch.setattr(train, "missing_train_deps", lambda: [])
     monkeypatch.setattr(cli, "_train", lambda *a, **k: pytest.fail("must not retrain"))
     cli.cmd_maintain(argparse.Namespace(min_new=5, base="small", epochs=1))
     assert "1 new labeled clips since v0001" in capsys.readouterr().out
 
 
+def test_maintain_without_train_extra_labels_and_exits_cleanly(monkeypatch, capsys):
+    """A nightly timer must not fail every night, or spend an eval, over an
+    optional install."""
+    import argparse
+
+    from voiceio.cli import learn as cli
+    labeled = []
+    monkeypatch.setattr(cli, "cmd_label", lambda args: labeled.append(True))
+    monkeypatch.setattr(train, "missing_train_deps", lambda: ["torch", "peft"])
+    monkeypatch.setattr(store, "build_dataset", lambda: pytest.fail("must not build"))
+    monkeypatch.setattr(cli, "_run_eval", lambda *a, **k: pytest.fail("must not eval"))
+    cli.cmd_maintain(argparse.Namespace(min_new=5, base="small", epochs=1))
+    assert labeled and "python-voiceio[train]" in capsys.readouterr().out
+
+
 def test_dev_mix_is_stable_per_row():
     assert train._row_draws("a.wav") == train._row_draws("a.wav")
     assert train._row_draws("a.wav") != train._row_draws("b.wav")

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/tests/test_service.py

@@ -43,3 +43,20 @@ def test_learn_timer_runs_maintain_at_idle_priority(monkeypatch, tmp_path):
 
     service.uninstall_learn_timer()
     assert not service.LEARN_TIMER_PATH.exists() and not service.LEARN_SERVICE_PATH.exists()
+
+
+def test_daemon_publishes_state_and_restart_waits_for_idle(monkeypatch):
+    import threading
+
+    from voiceio import config
+    from voiceio.app import VoiceIO, _State
+    from voiceio.cli.servicecmd import wait_until_idle
+
+    assert wait_until_idle(timeout=1)                 # not running: no wait
+    vio = VoiceIO.__new__(VoiceIO)
+    vio._state = _State.RECORDING
+    assert config.STATE_PATH.read_text() == "recording"
+    threading.Timer(0.3, lambda: setattr(vio, "_state", _State.IDLE)).start()
+    assert wait_until_idle(timeout=5, poll=0.05)      # waited for the dictation
+    vio._state = _State.FINALIZING
+    assert not wait_until_idle(timeout=0.2, poll=0.05)   # gives up, says so

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/tests/test_setup.py

@@ -265,3 +265,18 @@ def test_retention_is_written_only_when_asked(cfg_paths):
     assert config.load(cfg_paths).data.retain_audio is False      # off unless chosen
     configfile._write_config(**kw, retain_audio=True)
     assert config.load(cfg_paths).data.retain_audio is True
+
+
+def test_setup_offers_nightly_learning_once(monkeypatch):
+    from voiceio import service
+    from voiceio.setup import steps
+    installed = []
+    monkeypatch.setattr(service, "has_systemd", lambda: True)
+    monkeypatch.setattr(service, "learn_timer_enabled", lambda: bool(installed))
+    monkeypatch.setattr(service, "install_learn_timer", lambda: installed.append(1) or True)
+    asked = []
+    monkeypatch.setattr(steps, "_ask_yn", lambda q, default=True: asked.append(q) or True)
+    state = steps.SetupState(checks={"is_linux": True})
+    steps._offer_nightly_learning(state)
+    steps._offer_nightly_learning(state)      # already on: not asked again
+    assert installed == [1] and len(asked) == 1

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/tests/test_transcriber.py

@@ -313,3 +313,14 @@ def test_no_log_call_formats_the_transcript_itself():
                     and any(leaks(a) for a in node.args[1:])):
                 hits.append(f"{path.name}:{node.lineno}")
     assert not hits, hits
+
+
+def test_non_default_beam_is_scored_under_its_own_name():
+    """An eval at beam 1 must not stand in for the model's default score."""
+    mock_proc = MagicMock()
+    mock_proc.stdout.readline.return_value = "READY\n"
+    mock_proc.poll.return_value = None
+    with patch("voiceio.core.decoders.faster_whisper.subprocess.Popen", return_value=mock_proc):
+        from voiceio.core.decoders.faster_whisper import Transcriber
+        assert Transcriber(ModelConfig()).name == "faster-whisper:small"
+        assert Transcriber(ModelConfig(beam_size=1)).name == "faster-whisper:small@beam1"

python_voiceio-1.2.0/voiceio/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.2.0"

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/voiceio/app.py

@@ -36,6 +36,20 @@ class _State(enum.Enum):
 
 
 class VoiceIO:
+    @property
+    def _state(self) -> _State:
+        return self.__state
+
+    @_state.setter
+    def _state(self, value: _State) -> None:
+        self.__state = value
+        try:   # best-effort: only `service restart` reads it
+            tmp = config.STATE_PATH.with_suffix(".tmp")
+            tmp.write_text(value.value)
+            tmp.replace(config.STATE_PATH)
+        except OSError:
+            pass
+
     def __init__(self, cfg: config.Config):
         self.cfg = cfg
 
@@ -713,4 +727,5 @@ class VoiceIO:
             self._ibus.shutdown()
             self._pid_fd.close()
             PID_PATH.unlink(missing_ok=True)
+            config.STATE_PATH.unlink(missing_ok=True)
         log.info("voiceio stopped")

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/voiceio/cli/learn.py

@@ -63,6 +63,8 @@ def register(sub: argparse._SubParsersAction) -> None:
     e.add_argument("--pipeline", action="store_true",
                    help="no decoding: score what each text stage (corrections, numbers, "
                         "cloud postcorrect…) did to past dictations")
+    e.add_argument("--beam", type=int, default=None,
+                   help="beam width of the passes you keep (default: [model] beam_size)")
     e.add_argument("--speed", type=float, default=1.0,
                    help="streaming replay speed; >1 is faster but skews latency")
     e.set_defaults(func=cmd_eval)
@@ -334,12 +336,12 @@ def cmd_eval(args: argparse.Namespace) -> None:
     if ds is None or not ds.exists():
         raise SystemExit("no dataset — run `voiceio learn build` first")
     _run_eval(args.model, ds, limit=args.limit, streaming=args.streaming, lanes=args.lanes,
-              freeze=args.freeze, speed=args.speed)
+              freeze=args.freeze, speed=args.speed, beam=args.beam)
 
 
 def _run_eval(model: str | None, ds: Path, *, limit: int | None = None,
               streaming: bool = False, lanes: int | None = None,
-              freeze: float | None = None, speed: float = 1.0):
+              freeze: float | None = None, speed: float = 1.0, beam: int | None = None):
     """Score `model` (default: the configured one) on `ds`; print and save."""
     from voiceio.core.bias import BiasProvider
     from voiceio.core.decoders import build_decoder
@@ -348,6 +350,8 @@ def _run_eval(model: str | None, ds: Path, *, limit: int | None = None,
     cfg = _cfg()
     if model:
         cfg.model.name = model
+    if beam:
+        cfg.model.beam_size = beam
     print(f"Loading {cfg.model.name}…", flush=True)
     # Offline scoring needs one lane; streaming mirrors the live setup.
     decoder = build_decoder(cfg.model, lanes=lanes if lanes is not None else
@@ -428,6 +432,12 @@ def cmd_maintain(args: argparse.Namespace) -> None:
     _yield_cpu()
     from voiceio.learn import evaluate
     cmd_label(argparse.Namespace(teacher=None, limit=None, relabel=False))
+    from voiceio.learn import train
+    if missing := train.missing_train_deps():
+        # Labeling alone is worth it; retraining waits for the extra. Exit 0:
+        # a nightly timer must not fail every night over an optional install.
+        print(f"labeled; fine-tuning needs {', '.join(missing)}: {train.TRAIN_HINT}")
+        return
     labels = store.load_labels()
     labeled = {c.audio for c in store.clips() if c.audio in labels}
     ds = store.latest_dataset()
@@ -457,6 +467,10 @@ def cmd_schedule(args: argparse.Namespace) -> None:
         if not config.load().data.retain_audio:
             print("note: [data] retain_audio is off, so there is nothing new to learn from;\n"
                   "      turn it on with: voiceio config set data.retain_audio true")
+        from voiceio.learn import train
+        if missing := train.missing_train_deps():
+            print(f"note: until {', '.join(missing)} are installed it only labels new clips;\n"
+                  f"      to also retrain: {train.TRAIN_HINT}")
         if not service.install_learn_timer():
             raise SystemExit("could not enable the timer (needs systemd --user)")
         print("on: every night ~03:30, `voiceio learn maintain` labels new dictation at idle "

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/voiceio/cli/servicecmd.py

@@ -10,6 +10,8 @@ def register(sub: argparse._SubParsersAction) -> None:
     p.add_argument("action", nargs="?", default="status",
                    choices=["install", "uninstall", "start", "stop", "restart",
                             "status", "logs"])
+    p.add_argument("--now", action="store_true",
+                   help="stop/restart: don't wait for a dictation in progress to finish")
     p.add_argument("-f", "--follow", action="store_true", help="logs: follow")
     p.add_argument("-n", "--lines", type=int, default=50, help="logs: line count")
     p.set_defaults(func=_cmd_service)
@@ -61,6 +63,8 @@ def _cmd_service(args: argparse.Namespace) -> None:
             sys.exit(1)
 
     elif action in ("stop", "restart"):
+        if not getattr(args, "now", False):
+            wait_until_idle()
         try:
             subprocess.run(["systemctl", "--user", action, "voiceio.service"],
                            capture_output=True, timeout=10, check=True)
@@ -79,3 +83,25 @@ def _cmd_service(args: argparse.Namespace) -> None:
             subprocess.call(cmd)
         except KeyboardInterrupt:
             pass
+
+
+def wait_until_idle(timeout: float = 300.0, poll: float = 0.25) -> bool:
+    """Wait for the daemon to finish any dictation in progress (stopping it
+    mid-recording loses what was said). True once idle or not running."""
+    import time
+
+    from voiceio.config import STATE_PATH
+    deadline, told = time.monotonic() + timeout, False
+    while time.monotonic() < deadline:
+        try:
+            state = STATE_PATH.read_text().strip()
+        except OSError:
+            return True          # not running (or pre-1.1): nothing to wait for
+        if state in ("idle", "error"):
+            return True
+        if not told:
+            print(f"Waiting for the dictation in progress to finish ({state})…", flush=True)
+            told = True
+        time.sleep(poll)
+    print("Still busy; going ahead. (--now skips the wait.)", file=sys.stderr)
+    return False

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/voiceio/config.py

@@ -34,6 +34,9 @@ HISTORY_PATH = LOG_DIR / "history.jsonl"
 RECORDINGS_DIR = LOG_DIR / "recordings"
 LOG_PATH = LOG_DIR / "voiceio.log"
 PID_PATH = LOG_DIR / "voiceio.pid"
+# The daemon's state (idle/recording/finalizing), so `voiceio service
+# restart` can wait for a dictation to finish instead of killing it.
+STATE_PATH = Path(os.environ.get("XDG_RUNTIME_DIR", "/tmp")) / "voiceio.state"
 # Intermediate pipeline data kept for debugging/profiling and future training:
 # per-pass streaming decode traces and postcorrect before/after pairs. These
 # live in their own JSONL files (not the rotating log) so they survive.
@@ -76,6 +79,9 @@ class ModelConfig:
     # "modified_beam_search" (required for hotwords).
     decoding: str = ""
     vocabulary_file: str = ""  # path to vocabulary.txt
+    # Beam width of the passes whose text you keep (freezes and the final
+    # tail); interim previews are always greedy. 1 is greedy: faster stop.
+    beam_size: int = 5
     # Other languages you dictate in: a correction rule that would rewrite a
     # real word in one of these is flagged (e.g. ["es"] protects "harina").
     protect_languages: list[str] = field(default_factory=list)

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/voiceio/core/decoders/faster_whisper/__init__.py

@@ -93,6 +93,8 @@ class Transcriber:
     def __init__(self, cfg: ModelConfig):
         self._cfg = cfg
         self.name = f"faster-whisper:{cfg.name}"
+        if cfg.beam_size != 5:   # scored separately from the default
+            self.name += f"@beam{cfg.beam_size}"
         if _PROMPTLESS.search(cfg.name):
             self.capabilities = Capabilities(bias=BiasMode.NONE)
         self._proc: subprocess.Popen | None = None
@@ -205,7 +207,7 @@ class Transcriber:
 
             audio = normalize_audio(audio)
             audio_b64 = base64.b64encode(audio.tobytes()).decode("ascii")
-            req = {"audio_b64": audio_b64, "options": {"beam_size": 5 if final else 1}}
+            req = {"audio_b64": audio_b64, "options": {"beam_size": self._cfg.beam_size if final else 1}}
             # Cap the combined prompt. initial_prompt (recent transcripts) and
             # `context` (streaming's frozen-text tail) are both bounded in CHARS
             # by their callers, but nothing bounded their SUM in tokens — and

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/voiceio/health.py

@@ -217,6 +217,8 @@ def _check_features() -> FeatureGroups:
             else:
                 groups.accuracy["Vocabulary"] = "none"
 
+        groups.accuracy.update(_learning_status(cfg))
+
         if cfg.postcorrect.enabled:
             model = cfg.postcorrect.model or cfg.cloud.model
             groups.accuracy["Cloud postcorrect"] = f"on ({model}), adds up to {cfg.postcorrect.timeout_secs:g}s"
@@ -225,6 +227,30 @@ def _check_features() -> FeatureGroups:
     return groups
 
 
+def _learning_status(cfg) -> dict[str, str]:
+    """Whether voiceio is learning your voice: the model in use, whether
+    recordings are kept to learn from, and whether it retrains nightly."""
+    from pathlib import Path
+
+    from voiceio import config, service
+    from voiceio.learn.store import learn_dir
+    out: dict[str, str] = {}
+    models = learn_dir() / "models"
+    name = cfg.model.name
+    if models in Path(name).expanduser().parents:
+        out["Voice model"] = f"fine-tuned on you ({Path(name).parent.name})"
+    else:
+        out["Voice model"] = f"stock ({name})"
+    if cfg.data.retain_audio:
+        n = sum(1 for _ in config.RECORDINGS_DIR.glob("*.wav")) \
+            if config.RECORDINGS_DIR.exists() else 0
+        out["Recordings"] = f"on ({n} kept to learn from)"
+    else:
+        out["Recordings"] = "off (nothing to learn from)"
+    out["Nightly learning"] = "on" if service.learn_timer_enabled() else "off"
+    return out
+
+
 def _check_ibus() -> IBusStatus:
     """Run detailed IBus health checks."""
     from pathlib import Path
@@ -325,6 +351,10 @@ def _accuracy_tips(accuracy: dict[str, str]) -> list[str]:
         tips.append("voiceio corrections add WRONG RIGHT  — fix a word that keeps being misheard")
     if vocab == "none":
         tips.append("Add names/jargon to ~/.config/voiceio/vocabulary.txt")
+    if accuracy.get("Recordings", "").startswith("off"):
+        tips.append("voiceio config set data.retain_audio true  — keep recordings so voiceio can learn your voice")
+    elif accuracy.get("Nightly learning") == "off":
+        tips.append("voiceio learn schedule on  — retrain on your voice every night")
     return tips
 
 
@@ -391,7 +421,7 @@ def format_report(report: HealthReport) -> str:
     # Accuracy / learning stack
     if report.features.accuracy:
         lines.append(_section("Accuracy"))
-        lines.append(f"  {DIM}Learns from your dictation history to fix recurring mistakes.{RESET}")
+        lines.append(f"  {DIM}What voiceio knows about your words, and whether it keeps learning.{RESET}")
         for name, status in report.features.accuracy.items():
             lines.append(_feature_line(name, status))
         # Show actionable tips at the bottom

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/voiceio/learn/train.py

@@ -76,13 +76,17 @@ _DECODER_TARGETS = (r".*decoder\.layers\.\d+\.(self_attn\.(q_proj|k_proj|v_proj|
                     r"|encoder_attn\.(q_proj|out_proj)|fc1|fc2)")
 
 
+TRAIN_HINT = "pip install 'python-voiceio[train]'"
+
+
+def missing_train_deps() -> list[str]:
+    """Training packages that aren't installed (the `train` extra)."""
+    import importlib.util
+    return [m for m in ("torch", "transformers", "peft") if importlib.util.find_spec(m) is None]
+
+
 def require_train_deps() -> None:
-    missing = []
-    for mod in ("torch", "transformers", "peft"):
-        try:
-            __import__(mod)
-        except ImportError:
-            missing.append(mod)
+    missing = missing_train_deps()
     if missing:
         raise RuntimeError(
             f"training needs {', '.join(missing)}: pip install 'python-voiceio[train]'")

{python_voiceio-1.1.0 → python_voiceio-1.2.0}/voiceio/setup/steps.py

@@ -504,6 +504,8 @@ def _step_finalize(state: SetupState) -> None:
     state.retain_audio = _ask_yn("Keep recordings so voiceio can learn your voice?",
                                  default=state.cur.data.retain_audio if state.cur else True)
     _write_config(**state.config_kwargs())
+    if state.retain_audio:
+        _offer_nightly_learning(state)
     _setup_desktop_shortcut(state)
     _install_autostart(state)
     _verify_hotkey(state)
@@ -511,6 +513,24 @@ def _step_finalize(state: SetupState) -> None:
         _start_service()
 
 
+def _offer_nightly_learning(state: SetupState) -> None:
+    """The recordings are only worth keeping if something learns from them."""
+    from voiceio import service
+    if not state.checks["is_linux"] or not service.has_systemd() or service.learn_timer_enabled():
+        return
+    print(f"  {DIM}Every night at idle priority: transcribe new recordings with a bigger model,")
+    print(f"  retrain once enough are new, and tell you if the result is better.{RESET}")
+    if not _ask_yn("Learn from them every night?", default=True):
+        return
+    if service.install_learn_timer():
+        print(f"  {GREEN}✓{RESET} {DIM}Nightly learning on (voiceio learn schedule off to stop){RESET}")
+        from voiceio.learn import train
+        if missing := train.missing_train_deps():
+            print(f"  {DIM}Retraining also needs {', '.join(missing)}: {train.TRAIN_HINT}{RESET}")
+    else:
+        print(f"  {YELLOW}⚠{RESET}  {DIM}Could not enable it; try: voiceio learn schedule on{RESET}")
+
+
 def _setup_desktop_shortcut(state: SetupState) -> None:
     """Set up DE shortcut if on GNOME + socket backend (Linux only)."""
     if not state.checks["is_linux"]:

python_voiceio-1.1.0/voiceio/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.1.0"