python-voiceio 1.2.0__py3-none-any.whl → 1.4.0__py3-none-any.whl

{python_voiceio-1.2.0.dist-info → python_voiceio-1.4.0.dist-info}/METADATA

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.2.0
+Version: 1.4.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/Hugo0/voiceio
+Project-URL: Homepage, https://voiceio.dev/
 Project-URL: Repository, https://github.com/Hugo0/voiceio
 Project-URL: Issues, https://github.com/Hugo0/voiceio/issues
 Project-URL: Changelog, https://github.com/Hugo0/voiceio/releases
@@ -58,7 +58,7 @@ Dynamic: license-file
 [![Python](https://img.shields.io/pypi/pyversions/python-voiceio)](https://pypi.org/project/python-voiceio/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**Voice dictation that learns you.** Local, open source, private — and it fine-tunes itself on your own voice, on your own machine.
+**Voice dictation that learns you.** ([website](https://voiceio.dev/)) Local, open source, private — and it fine-tunes itself on your own voice, on your own machine.
 
 Off-the-shelf speech models stumble on exactly the words you say most: your colleagues' names, your project, your jargon. voiceio keeps (with your permission) the audio of what you dictate, has a bigger model transcribe it overnight, and trains a personal model from it — nothing uploaded, no GPU required. On the author's dictation, one overnight run on a laptop CPU cut word errors from **12.1% to 5.0%** on held-out clips and recognized more of the author's vocabulary, at the same speed. Every model is scored on clips it never trained on, and it only replaces the current one when it wins.
 
@@ -182,7 +182,8 @@ Most dictation errors are proper nouns and jargon: `PostgreSQL` heard as `post g
 voiceio learn import DIR --source phone   # optional: add your own recordings from elsewhere
 voiceio learn label      # a stronger teacher model (large-v3-turbo) transcribes your clips
 voiceio learn review     # fix the teacher where it matters: your names and terms
-voiceio learn review --test   # once: verify the held-out clips, so eval scores against the truth
+voiceio learn review --test   # verify the held-out clips, so eval scores against the truth: it asks only
+                              #   where the teacher and your live decode disagree, quickest clips first
 voiceio learn augment    # synthesize extra examples of rare terms with local TTS
 voiceio learn build      # freeze a versioned train/dev/test dataset (the test split never trains)
 voiceio learn eval       # score the current model on your held-out clips: WER and term recall
@@ -190,9 +191,16 @@ voiceio learn eval       # score the current model on your held-out clips: WER a
 voiceio learn train      # LoRA fine-tune (needs the `train` extra; decoder-only on CPU, --full on a GPU)
 voiceio learn promote <run>   # dictate with the fine-tune; `voiceio learn rollback` undoes it
 voiceio learn maintain   # later: label what's new, and once 50+ clips piled up, retrain and compare
-voiceio learn schedule on   # …or let it run `maintain` every night, and notify you when a model wins
+voiceio learn schedule on   # …or let it run `maintain` on a schedule, and notify you when a model wins
+                            #   --at 02:00 --every week: when (default daily at 03:30)
+                            #   --auto-promote: switch to a winner by itself; `learn rollback` undoes it
+voiceio learn stop          # stop a run in progress (it goes again next time)
 ```
 
+Scheduled runs wait for a quiet machine: they start only when the 1-minute load per CPU is at most `[learn] max_load` (0.25) and you're on mains power, and give up after `wait_hours` (3) until the next run. When one starts you get a notification with **Stop for now** and **Weekly instead**.
+
+To keep a second machine (say, the server your phone dictates through) on the same model, set `[learn] on_promote = "scripts/push_model.sh HOST"`: after every switch it copies the model there and flips a `current` link the server points at.
+
 Labeling, training and offline eval run in an idle-priority cgroup, so they never slow dictation down. Everything stays on your machine unless you choose `train --remote`.
 
 `voiceio learn status` shows where you are, each model's scores, and suggests `promote` only when a fine-tune wins on everything. `promote` itself refuses a model that hasn't, and reports how many clips got better or worse with a confidence interval — a few dozen test clips can move an average by luck.
@@ -300,8 +308,6 @@ 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 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.2.0.dist-info → python_voiceio-1.4.0.dist-info}/RECORD

@@ -1,24 +1,24 @@
-python_voiceio-1.2.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
-voiceio/__init__.py,sha256=MpAT5hgNoHnTtG1XRD_GV_A7QrHVU6vJjGSw_8qMGA4,22
+python_voiceio-1.4.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
+voiceio/__init__.py,sha256=8UhoYEXHs1Oai7BW_ExBmuwWnRI-yMG_u1fQAXMizHQ,22
 voiceio/__main__.py,sha256=xT5QCGGreYMisHO7Lh_Y-xAQ2TOzG2D7npKknGNcWSY,53
-voiceio/app.py,sha256=_FfrMN1MFWk8H5KciGu2niJm3fZJlNR2Ju9mP9s5brk,31798
+voiceio/app.py,sha256=K9vz9iZRRTavyWNYaZMYxwsvaPJBRYcQjFFyi4YOfOM,32164
 voiceio/audio_source.py,sha256=rR6NRtNzmZ8uqmNPxareBWTJmuBaOxIGI5QINR_l-qc,9102
 voiceio/backends.py,sha256=-rs1YhPblub4NjFb6qCD7Ih9FqBRXtPuvjVv9bQoQ1w,368
 voiceio/clipboard_read.py,sha256=lz75CkRGh7pyvO6xvoUmxJDl-Gwie1xlXQHK70PO84I,4261
 voiceio/commands.py,sha256=Jz-txXSw32Adf8B912M8CzQIh4UMmEKRCZBPXU4bBaU,6014
-voiceio/config.py,sha256=2QrttnGz0Cc7fLrlmhLA0-Nfvz1jJv9ea4kfY6icOEI,19522
+voiceio/config.py,sha256=X1W5Vc5HgegMsRgXD074h3txhNwewUf9DaKkRglmPf0,20337
 voiceio/consent.py,sha256=3stv3iZvYl_Dt4GUe-GUVOHEGi-2fOl-QqF3pDjraS4,1862
 voiceio/corrections.py,sha256=IIRViwjL9kkMy26-1dd0DtTfT0Tiedn6pmmHoaeayMQ,10047
 voiceio/demo.py,sha256=jA282e7UWDwtP1IXT2bPHH5wl6eKdBNvOJcoNDWzZlQ,8766
 voiceio/display.py,sha256=ZGBNRjuvg3chkJjduyPJs4s5ZY5vqC_mcaov94PIPzo,5313
-voiceio/feedback.py,sha256=i1Hkd_bydOOQ8p19Bz4bYougjQtozKGLjfKc5DKRDT0,5711
-voiceio/health.py,sha256=r0nMDozuhk1nZNpCiVhmezC_7P6ElQpaBB_IomzmXF8,22166
+voiceio/feedback.py,sha256=avTjD8wksjStPkGVc_Z2lTMpalhwn7NmI3RZ2USvOLc,7066
+voiceio/health.py,sha256=6cdVMq4pr9WQS8YN7ikxtoCYESXLU4_z7gT3XYo-33Y,22154
 voiceio/hints.py,sha256=dmoiMAJ0YGTWwFc9kIPvEs_BQJN7UEUiwYuLUD_GoQQ,1415
 voiceio/history.py,sha256=cD3Ysa39qt6uKbrcLeRQt-FOJcYCoqie4UNsUWF7DuM,5763
 voiceio/llm.py,sha256=cO2RHM2zHxTD4r5mFFNatB-pjOSl29Wx_I00f7ywYCw,9161
 voiceio/llm_api.py,sha256=4jJ5U1Dop-3uoM9RM3bjUMxB4kYNNjwKbOwIIj0ll3U,9390
 voiceio/numbers.py,sha256=CXJtlMhmV6_9Z1FtKAF4-RXycw8voV-BYHPBpdw1I6Y,13571
-voiceio/pidlock.py,sha256=RInlF_8H7wR0nqkdlhUfxYs7OGzHIvb5p-XDjjQSTNg,619
+voiceio/pidlock.py,sha256=OZLNskUyv9_F3WgyHZWw8WmKt0W7ioxH6xgHitOwCww,1216
 voiceio/platform.py,sha256=uG_5KeYey_29GCn4nSOQJ1UpoCrBC_m2DR7IeoRnuL4,19142
 voiceio/postcorrect.py,sha256=JN5l9xnyGfYq2_owSUwkJ513QiQQKxCrT3hjU5aJCpg,17322
 voiceio/postprocess.py,sha256=rzKmf_ZCskhGnqLEbHaiQX-Sz9yutdJwcwposz7GJ4Q,4661
@@ -26,7 +26,7 @@ voiceio/privacy.py,sha256=FqnA9jx9RCqWW-i6Dh7JcT7vzz97kbUGyQEvsHLvpqc,573
 voiceio/prompt.py,sha256=9iza8KoQxvO_U9NPMJ8Ep7j-zkIs9nW8N5sacCRpsEk,2904
 voiceio/recorder.py,sha256=k51Py6av0YFkc1ENXsrXuFIL3G9bmsAijGq3X5r7pG4,15734
 voiceio/retention.py,sha256=TH_D29EUYyzEPl5FK0q32mpsSk0-0bx56JwAH83FBHI,6272
-voiceio/service.py,sha256=_cTb1AQ57cF8-eW3SKvDkCP46S5yJqhty1fe_eI8zbQ,14324
+voiceio/service.py,sha256=q4_Mk8m3KCG14CGZ468ZrFvNvyXuWSOjKFUjRnksgAI,16391
 voiceio/streaming.py,sha256=hKak7ULkZbkHl5Fw0SnnZsEK3alv2s8dcuCcyBzpIQY,24700
 voiceio/suggest.py,sha256=jX4bCpnddyrteKfRBPbnUgf-Rk5145LFaSTat0_Ll2E,4836
 voiceio/tokens.py,sha256=m5tusR3zEBX7fRKaDUj4z-DSv8NcMhE-02HviAziENQ,5710
@@ -41,9 +41,9 @@ voiceio/cli/configcmd.py,sha256=YF7t-LkwEYEGH4qcO86xehWVX0LvltqxjDFpMF5ljjA,2858
 voiceio/cli/corrections.py,sha256=OBjgiOhtWlTQpQq0HLAvk5-EfKJ7NNt-hnNBHm7obEc,4247
 voiceio/cli/doctor.py,sha256=P8bOn4xedMistlKHhNeeGxRsmogV6jBVKc-CUbo0LXs,7769
 voiceio/cli/history.py,sha256=IWyFIozX5PUwtrU17JlkNea9nP_oKLsXfkxIVHjkfD0,1516
-voiceio/cli/learn.py,sha256=cQ3HOf0LXybRf-40QA6Jvb54gy7rpCCz_2xavPJE7wk,24859
+voiceio/cli/learn.py,sha256=W-7FQIcrtVlCC8SBNHkhUnE8iK0m6WiHsE8qlxz0BE4,31056
 voiceio/cli/models.py,sha256=fye_mHbsXLY11uRC1BCDlucCHPny9ftoehAeUJPMJv0,4263
-voiceio/cli/servicecmd.py,sha256=hcaQD1NL38fvkrHtId1307MIgyi2O2xBP6YvG8CTngc,4219
+voiceio/cli/servicecmd.py,sha256=2St2WfLkt06EpC51I5i9Ykv_pvLKzu_dz01M-29O3-4,4830
 voiceio/cli/uninstall.py,sha256=Vqnq6-4hjhDrxqkU_1wtXkY5BU_Tqa-TjZA0Qpf12e4,8921
 voiceio/cli/vocab.py,sha256=lxxuSukefvIHV4fFSduCQQewXY0_Bvf5sDnG4bqLWH8,4418
 voiceio/core/__init__.py,sha256=K0b4duczohS3IrIMLp9fYhfb-GeuyQaOVH_8teYGsQM,277
@@ -75,10 +75,11 @@ voiceio/ibus/textlimit.py,sha256=4Hmn2LDEOs7h-Hb2-cT1HkvIRepDgZq4KRI9KD3xiBQ,251
 voiceio/learn/__init__.py,sha256=Q98-C809lkMqTS0OAV1xNVtqHz9NvuekivXiHiVHBWA,750
 voiceio/learn/augment.py,sha256=qyegRlg3cQF5CT0HV85Jm93Jd9xZpjWwbFVk_VzFdiI,4105
 voiceio/learn/clean.py,sha256=1ItIfIAsqxZLZ76T4oF7kSr4Poo-z_6GEzhrlt21uMo,4922
-voiceio/learn/evaluate.py,sha256=_a1sIum_T2f5lEVJ9-4VjgXOwmLh-B8R1PI7C7zmWH8,12600
+voiceio/learn/evaluate.py,sha256=sW2lfV9jK22fpFFgxh9p6cp0pcTt5KjXV3eatsrg9sM,13233
 voiceio/learn/importer.py,sha256=uB-gHWwSewZYTx22j9h941ARtDE8BFHmf8p3HaHUC6g,3544
 voiceio/learn/metrics.py,sha256=b2xWUzPpNpXHn6zgS1upPbEcpW3ExH9SmSLIUzPhStQ,5174
-voiceio/learn/review.py,sha256=p11kRY-PF9YhS7aYjcYpDUJavUn8OXXz4d6S-MGfCGE,4575
+voiceio/learn/quiet.py,sha256=TgKRlUMbXLCgiIv2i7ukcy0L0KbuhMPdD6tgvntZ1Ek,1973
+voiceio/learn/review.py,sha256=X5qs5yEf20Ao3gMhsbW3Eur62hSqy9AYlv08Pcrllxo,5572
 voiceio/learn/store.py,sha256=MauWhGaI2drMbiChIZOblpPS_uVAw-1sNWGyGACHYw8,12816
 voiceio/learn/teacher.py,sha256=uF4hQkrdjv012TTBRSwrhQqqAeCFNoidABcrgzSVUoI,3696
 voiceio/learn/train.py,sha256=zTyftCsUV6hYy9WA8ftZtqjVbYJ-C7py0EoxavXWr7I,17628
@@ -125,8 +126,8 @@ voiceio/typers/pynput_type.py,sha256=Rzkixn08iaIqSCZ5vRybaHpn05lkx4FiEa_OakaiM1A
 voiceio/typers/wtype.py,sha256=d1wG-HZdYDQxXIysV_Xvk9HixDpaJgl3VEoKbP5vhIs,1786
 voiceio/typers/xdotool.py,sha256=dh1zhPqUT8ihJahJ7ZKm6PtfYY087UAzADx664DvQOM,1356
 voiceio/typers/ydotool.py,sha256=e19GvDHL9GS-jgh_hzW3PGBFPCc4IJCWsBWEzU_LqGs,5934
-python_voiceio-1.2.0.dist-info/METADATA,sha256=zEVw8vdKC4meGy8FxLLwba5SoZAb3LPu5OfTYlsusYo,21153
-python_voiceio-1.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-python_voiceio-1.2.0.dist-info/entry_points.txt,sha256=iDIDmhvQ3xeN_CWsFne1t9STZ08I25I_wp0xmde_vMs,94
-python_voiceio-1.2.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
-python_voiceio-1.2.0.dist-info/RECORD,,
+python_voiceio-1.4.0.dist-info/METADATA,sha256=zPfUJe5stD9z-kj9POKXJoW5WwCgeSztu_gIYTPIONg,21752
+python_voiceio-1.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+python_voiceio-1.4.0.dist-info/entry_points.txt,sha256=iDIDmhvQ3xeN_CWsFne1t9STZ08I25I_wp0xmde_vMs,94
+python_voiceio-1.4.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
+python_voiceio-1.4.0.dist-info/RECORD,,

voiceio/__init__.py

@@ -1 +1 @@
-__version__ = "1.2.0"
+__version__ = "1.4.0"

voiceio/app.py

@@ -43,6 +43,10 @@ class VoiceIO:
     @_state.setter
     def _state(self, value: _State) -> None:
         self.__state = value
+        # Only the instance holding the PID lock speaks for the daemon: a
+        # second launch must not overwrite the running one's state.
+        if not getattr(self, "_publishes_state", False):
+            return
         try:   # best-effort: only `service restart` reads it
             tmp = config.STATE_PATH.with_suffix(".tmp")
             tmp.write_text(value.value)
@@ -660,7 +664,7 @@ class VoiceIO:
         self._typers.redetect_at_start()
 
         LOG_DIR.mkdir(parents=True, exist_ok=True)
-        self._pid_fd = open(PID_PATH, "w")
+        self._pid_fd = open(PID_PATH, "a")   # not "w": the running daemon's PID stays
         try:
             from voiceio.pidlock import lock_pid_file
             lock_pid_file(self._pid_fd)
@@ -669,8 +673,11 @@ class VoiceIO:
             log.error("Another voiceio instance is already running")
             print("voiceio is already running. Stop it first: voiceio service stop")
             return
+        self._pid_fd.truncate(0)
         self._pid_fd.write(str(os.getpid()))
         self._pid_fd.flush()
+        self._publishes_state = True
+        self._state = self._state
 
         self._typers.prepare()
 

voiceio/cli/learn.py

@@ -84,12 +84,25 @@ def register(sub: argparse._SubParsersAction) -> None:
                     help="new labeled clips needed before retraining (default 50)")
     mt.add_argument("--base", default="small")
     mt.add_argument("--epochs", type=int, default=4)
+    mt.add_argument("--auto-promote", action="store_true",
+                    help="switch to the fine-tune when it wins, and restart the daemon")
+    mt.add_argument("--when-idle", action="store_true",
+                    help="first wait for a quiet machine on mains power ([learn] max_load, "
+                         "wait_hours); the scheduled run uses this")
     mt.set_defaults(func=cmd_maintain)
 
-    sc = lsub.add_parser("schedule", help="Run `maintain` every night (systemd timer)")
+    sc = lsub.add_parser("schedule", help="Run `maintain` on a schedule (systemd timer)")
     sc.add_argument("state", nargs="?", choices=("on", "off"), help="omit to show")
+    sc.add_argument("--at", help="time of day, e.g. 02:00 (saved as [learn] at; default 03:30)")
+    sc.add_argument("--every", choices=("day", "week"),
+                    help="daily, or weekly on Sunday (saved as [learn] every)")
+    sc.add_argument("--auto-promote", action="store_true",
+                    help="with on: switch to a fine-tune that wins, without asking")
     sc.set_defaults(func=cmd_schedule)
 
+    st = lsub.add_parser("stop", help="Stop a scheduled learning run that is in progress")
+    st.set_defaults(func=cmd_stop)
+
     pr = lsub.add_parser("promote", help="Use a trained model for dictation")
     pr.add_argument("run", help="run name under learn/models (see `learn status`)")
     pr.add_argument("--force", action="store_true",
@@ -182,8 +195,7 @@ def cmd_status(args: argparse.Namespace) -> None:
         print(f"models     {', '.join(runs)}")
     active = _cfg().model.name
     print(f"active     {active}")
-    from voiceio import service
-    print(f"nightly    {'on' if service.learn_timer_enabled() else 'off (voiceio learn schedule on)'}")
+    print(f"nightly    {_schedule_state()}")
     promotable = _print_scores(ds, active, runs) if ds else None
     if promotable:
         nxt = f"promote {promotable}"
@@ -197,9 +209,9 @@ def _print_scores(ds: Path, active: str, runs: list[str]) -> str | None:
     """Scores on `ds` for the active model and each fine-tune; returns the
     run that beats the active model on everything, if any."""
     from voiceio.learn import evaluate
-    current = evaluate.latest(active, ds.name)
+    current = evaluate.latest(active, ds.name, beam=_cfg().model.beam_size)
     rows = [(active + " (active)", current)] + [
-        (run, evaluate.latest(str(_models_dir() / run / "ct2"), ds.name)) for run in runs]
+        (run, evaluate.latest(str(_models_dir() / run / "ct2"), ds.name, beam=_cfg().model.beam_size)) for run in runs]
     if not any(r for _, r in rows):
         return None
     print(f"\nscores on {ds.name} test clips:")
@@ -430,7 +442,12 @@ def cmd_maintain(args: argparse.Namespace) -> None:
     """Label what's new; once enough has piled up, rebuild, retrain and say
     whether the result beats the current model. Never promotes by itself."""
     _yield_cpu()
-    from voiceio.learn import evaluate
+    from voiceio.learn import evaluate, quiet
+    learn_cfg = _cfg().learn
+    if getattr(args, "when_idle", False) and not quiet.wait_until_quiet(
+            learn_cfg.max_load, learn_cfg.wait_hours):
+        return
+    _announce_learning(args.min_new)
     cmd_label(argparse.Namespace(teacher=None, limit=None, relabel=False))
     from voiceio.learn import train
     if missing := train.missing_train_deps():
@@ -442,8 +459,9 @@ def cmd_maintain(args: argparse.Namespace) -> None:
     labeled = {c.audio for c in store.clips() if c.audio in labels}
     ds = store.latest_dataset()
     new = len(labeled - store.dataset_clips(ds)) if ds else len(labeled)
-    if ds is not None and new < args.min_new:
-        print(f"{new} new labeled clips since {ds.name}; retraining waits for {args.min_new}.")
+    if new < args.min_new:   # the first dataset too: a handful of clips trains nothing
+        since = f" since {ds.name}" if ds else ""
+        print(f"{new} new labeled clips{since}; retraining waits for {args.min_new}.")
         return
     ds = store.build_dataset()
     print(f"built {ds.name} ({new} new clips)")
@@ -454,15 +472,101 @@ def cmd_maintain(args: argparse.Namespace) -> None:
     print(f"\n{_cfg().model.name} → {run.name} on {ds.name}:\n{table}")
     print(f"better or equal on everything — `voiceio learn promote {run.name}`" if ok
           else "not better on everything — keeping the current model")
-    if ok:   # often runs unattended at night: say so where it will be seen
-        from voiceio import feedback
+    if not ok:
+        return
+    # Often runs unattended at night: say so where it will be seen.
+    from voiceio import feedback
+    if getattr(args, "auto_promote", False):
+        try:
+            cmd_promote(argparse.Namespace(run=run.name, force=False))
+        except SystemExit as refused:   # the gate's own re-check said no
+            print(f"not promoted: {refused}")
+            return
+        from voiceio import service
+        if service.is_installed() and not service.restart_when_idle():
+            feedback.notify("VoiceIO: a better model is ready",
+                            f"Switched to {run.name}; restart voiceio to use it "
+                            "(a dictation was in progress). Undo: voiceio learn rollback",
+                            urgent=True)
+            return
+        feedback.notify("VoiceIO: switched to a better model",
+                        f"Trained on your dictation: {run.name}. Undo: voiceio learn rollback",
+                        urgent=True)
+    else:
         feedback.notify("VoiceIO: a better model is ready",
                         f"Trained on your dictation. Use it: voiceio learn promote {run.name}",
                         urgent=True)
 
 
+def _announce_learning(min_new: int) -> None:
+    """Tell the user a run is starting (it takes a while and uses the CPU),
+    with buttons to stop it or to learn weekly instead. Silent when there is
+    nothing to do."""
+    labels = store.load_labels()
+    clips = [c.audio for c in store.clips()]
+    to_label = sum(1 for a in clips if a not in labels)
+    ds = store.latest_dataset()
+    new = len(set(clips) - (store.dataset_clips(ds) if ds else set()))
+    retrain = new >= min_new
+    if not to_label and not retrain:
+        return
+    from voiceio import feedback
+    what = (f"Labeling {to_label} new recordings" if to_label else "") + \
+        (", then retraining" if to_label and retrain else "Retraining" if retrain else "")
+    feedback.notify_actions(
+        "VoiceIO is learning your voice",
+        f"{what}, on this computer at idle priority; dictation stays fast.",
+        {"stop": "Stop for now", "weekly": "Weekly instead"},
+        _on_learning_action)
+
+
+def _on_learning_action(key: str) -> None:
+    import signal
+
+    from voiceio import config, feedback, service
+    if key == "weekly":
+        config.set_value("learn", "every", "week")
+        service.install_learn_timer(auto_promote=service.learn_timer_auto_promotes())
+        feedback.notify("VoiceIO: learning weekly now",
+                        f"{service.learn_schedule_summary()}. This run continues; "
+                        "change it with voiceio learn schedule on --every day")
+    elif key == "stop":
+        # Under the timer, stop the unit so training subprocesses go too.
+        if not (os.environ.get("INVOCATION_ID") and service.stop_learning()):
+            os.kill(os.getpid(), signal.SIGINT)
+
+
+def _schedule_state() -> str:
+    from voiceio import service
+    summary = service.learn_schedule_summary()
+    return "off (voiceio learn schedule on)" if summary == "off" else f"on, {summary}"
+
+
+def cmd_stop(args: argparse.Namespace) -> None:
+    from voiceio import service
+    if not service.learning_now():
+        print("no learning run in progress")
+    elif service.stop_learning():
+        print("stopped; it runs again at the next scheduled time")
+    else:
+        raise SystemExit("could not stop voiceio-learn.service")
+
+
 def cmd_schedule(args: argparse.Namespace) -> None:
     from voiceio import config, service
+    if args.at or args.every:
+        learn = config.load().learn
+        try:   # validate before saving: the timer is generated from these
+            service.learn_calendar(args.at or learn.at, args.every or learn.every)
+        except ValueError as e:
+            raise SystemExit(str(e)) from None
+        for key in ("at", "every"):
+            if getattr(args, key):
+                config.set_value("learn", key, getattr(args, key))
+        if args.state is None and service.learn_timer_enabled():   # reschedule in place
+            service.install_learn_timer(auto_promote=service.learn_timer_auto_promotes())
+            print(f"on, {service.learn_schedule_summary()}")
+            return
     if args.state == "on":
         if not config.load().data.retain_audio:
             print("note: [data] retain_audio is off, so there is nothing new to learn from;\n"
@@ -471,16 +575,21 @@ def cmd_schedule(args: argparse.Namespace) -> None:
         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():
+        if not service.install_learn_timer(auto_promote=args.auto_promote):
             raise SystemExit("could not enable the timer (needs systemd --user)")
-        print("on: every night ~03:30, `voiceio learn maintain` labels new dictation at idle "
-              "priority, retrains once 50+ clips are new, and tells you if the result is better. "
-              "It never switches models by itself.")
+        learn = config.load().learn
+        print(f"on, {service.learn_schedule_summary()}: once the machine is quiet (load per CPU "
+              f"≤ {learn.max_load:g}, on mains power; waits up to {learn.wait_hours:g} h), "
+              "`voiceio learn maintain` labels new dictation at idle priority, retrains once "
+              "50+ clips are new, and "
+              + ("switches to the result when it wins on your held-out clips "
+                 "(undo: voiceio learn rollback)." if args.auto_promote else
+                 "tells you if the result is better. It never switches models by itself."))
     elif args.state == "off":
         service.uninstall_learn_timer()
         print("off")
     else:
-        print("on" if service.learn_timer_enabled() else "off — enable: voiceio learn schedule on")
+        print(_schedule_state())
 
 
 def _scores(result) -> dict:
@@ -500,22 +609,44 @@ def cmd_promote(args: argparse.Namespace) -> None:
         f.write(json.dumps({"ts": time.time(), "from": _cfg().model.name, "to": str(ct2)}) + "\n")
     set_value("model", "name", str(ct2))
     print(f"now dictating with {args.run} — restart the daemon: voiceio service restart")
+    _on_promote(str(ct2))
+
+
+def _on_promote(model: str) -> None:
+    """Run `[learn] on_promote` for a model switch. Its failure is reported,
+    never fatal: the switch on this machine already happened."""
+    import os
+    import subprocess
+    cmd = _cfg().learn.on_promote
+    if not cmd:
+        return
+    print(f"on_promote: {cmd}", flush=True)
+    try:
+        rc = subprocess.run(cmd, shell=True, env={**os.environ, "VOICEIO_MODEL": model},
+                            timeout=3600).returncode
+    except subprocess.TimeoutExpired:
+        rc = "timeout"
+    if rc != 0:
+        print(f"on_promote failed ({rc})")
+        from voiceio import feedback
+        feedback.notify("VoiceIO: model switched here, but on_promote failed",
+                        f"`{cmd}` exited {rc}; run it again by hand.")
 
 
 def _check_beats_current(ct2: Path) -> None:
     """Refuse a promotion the evals don't support (a fine-tune can regress)."""
     from voiceio.learn import evaluate
     ds = store.latest_dataset()
-    current = _cfg().model.name
+    current, beam = _cfg().model.name, _cfg().model.beam_size
     if ds is None:
         raise SystemExit("no dataset to compare on — `voiceio learn build`, or --force")
-    missing = [m for m in (current, str(ct2)) if evaluate.latest(m, ds.name) is None]
+    missing = [m for m in (current, str(ct2)) if evaluate.latest(m, ds.name, beam=beam) is None]
     if missing:
         raise SystemExit("evaluate both models on the same clips first:\n"
                          + "".join(f"  voiceio learn eval --model {m}\n" for m in missing)
                          + "(or promote anyway with --force)")
-    ok, table = evaluate.promotion_verdict(evaluate.latest(str(ct2), ds.name),
-                                           evaluate.latest(current, ds.name))
+    ok, table = evaluate.promotion_verdict(evaluate.latest(str(ct2), ds.name, beam=beam),
+                                           evaluate.latest(current, ds.name, beam=beam))
     print(f"on {ds.name} test clips, {current} → fine-tune:\n{table}")
     if not ok:
         raise SystemExit("the fine-tune is worse on something — not promoting (--force overrides)")
@@ -531,3 +662,4 @@ def cmd_rollback(args: argparse.Namespace) -> None:
     set_value("model", "name", last["from"])
     history.write_text("".join(r + "\n" for r in rows[:-1]))
     print(f"back to {last['from']} — restart the daemon: voiceio service restart")
+    _on_promote(last["from"])

voiceio/cli/servicecmd.py

@@ -85,23 +85,35 @@ def _cmd_service(args: argparse.Namespace) -> None:
             pass
 
 
-def wait_until_idle(timeout: float = 300.0, poll: float = 0.25) -> bool:
+def wait_until_idle(timeout: float = 300.0, poll: float = 0.25,
+                    finalizing_timeout: float = 60.0) -> 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."""
+    mid-recording loses what was said). True once idle or not running; False
+    when it stayed busy. A decode stuck finalizing gets a shorter wait: a
+    restart is how that is recovered."""
     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
+    from voiceio.config import PID_PATH, STATE_PATH
+    from voiceio.pidlock import daemon_alive
+    start, told = time.monotonic(), False
+    try:
+        while True:
+            if not daemon_alive(PID_PATH):
+                return True      # crashed or stopped: its state file is stale
+            try:
+                state = STATE_PATH.read_text().strip()
+            except OSError:
+                return True      # pre-1.1 daemon: nothing to wait for
+            if state in ("idle", "error"):
+                return True
+            waited = time.monotonic() - start
+            if waited > (finalizing_timeout if state == "finalizing" else timeout):
+                print(f"Still {state}; going ahead. (--now skips the wait.)", file=sys.stderr)
+                return False
+            if not told:
+                print(f"Waiting for the dictation in progress to finish ({state})…", flush=True)
+                told = True
+            time.sleep(poll)
+    except KeyboardInterrupt:
+        print("\nNot waiting.", file=sys.stderr)
+        sys.exit(130)

voiceio/config.py

@@ -243,6 +243,23 @@ class DataConfig:
     capture_intermediates: bool = False
 
 
+@dataclass
+class LearnConfig:
+    # A command run after every model switch (promote, auto-promote,
+    # rollback), with the model in $VOICEIO_MODEL — e.g. to push a fine-tune
+    # to another machine: scripts/push_model.sh HOST. Empty: nothing runs.
+    on_promote: str = ""
+    # When nightly learning runs (`voiceio learn schedule on`): a time of day,
+    # and "day" or "week" (weekly runs on Sunday).
+    at: str = "03:30"
+    every: str = "day"
+    # It only starts on a quiet machine on mains power: 1-minute load per CPU
+    # at most max_load. It waits up to wait_hours for that, then tries again
+    # at the next scheduled run.
+    max_load: float = 0.25
+    wait_hours: float = 3.0
+
+
 @dataclass
 class Config:
     hotkey: HotkeyConfig = field(default_factory=HotkeyConfig)
@@ -260,6 +277,7 @@ class Config:
     health: HealthConfig = field(default_factory=HealthConfig)
     data: DataConfig = field(default_factory=DataConfig)
     history: HistoryConfig = field(default_factory=HistoryConfig)
+    learn: LearnConfig = field(default_factory=LearnConfig)
 
 
 _REMOVED_KEYS = {
@@ -340,6 +358,7 @@ def load(path: Path | None = None) -> Config:
         health=_build(HealthConfig, raw.get("health", {})),
         data=_build(DataConfig, raw.get("data", {})),
         history=_build(HistoryConfig, raw.get("history", {})),
+        learn=_build(LearnConfig, raw.get("learn", {})),
     )
 
 

voiceio/feedback.py

@@ -14,6 +14,7 @@ import shutil
 import subprocess
 import threading
 import wave
+from collections.abc import Callable
 from pathlib import Path
 
 import numpy as np
@@ -151,6 +152,39 @@ def _send_notification_linux(title: str, body: str, urgent: bool = False) -> Non
         pass
 
 
+def notify_actions(title: str, body: str, actions: dict[str, str],
+                   on_action: Callable[[str], None]) -> None:
+    """A notification with buttons ({key: label}); ``on_action(key)`` runs
+    when one is clicked. Linux only; elsewhere, or with a notify-send too old
+    for actions, it degrades to a plain notification. Never blocks."""
+    import sys
+    if sys.platform != "linux" or not _which("notify-send") or not _notify_send_has_actions():
+        notify(title, body)
+        return
+
+    def wait() -> None:
+        args = ["notify-send", "--app-name=VoiceIO", "--wait",
+                *(f"--action={k}={label}" for k, label in actions.items()), title, body]
+        try:
+            picked = subprocess.run(args, capture_output=True, text=True).stdout.strip()
+        except OSError:
+            return
+        if picked in actions:
+            on_action(picked)
+
+    threading.Thread(target=wait, daemon=True).start()
+
+
+@functools.lru_cache(maxsize=1)
+def _notify_send_has_actions() -> bool:
+    """--action/--wait arrived in libnotify 0.7.9."""
+    try:
+        return "--action" in subprocess.run(["notify-send", "--help"], capture_output=True,
+                                            text=True, timeout=3).stdout
+    except (subprocess.TimeoutExpired, OSError):
+        return False
+
+
 def _send_notification_windows(title: str, body: str) -> None:
     try:
         from win11toast import notify

voiceio/health.py

@@ -247,7 +247,7 @@ def _learning_status(cfg) -> dict[str, str]:
         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"
+    out["Scheduled learning"] = service.learn_schedule_summary()
     return out
 
 
@@ -353,7 +353,7 @@ def _accuracy_tips(accuracy: dict[str, str]) -> list[str]:
         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":
+    elif accuracy.get("Scheduled learning") == "off":
         tips.append("voiceio learn schedule on  — retrain on your voice every night")
     return tips
 

voiceio/learn/evaluate.py

@@ -156,11 +156,11 @@ def save(result: EvalResult) -> Path:
     return path
 
 
-def latest(model: str, dataset: str, mode: str = "offline") -> dict | None:
-    """The newest saved run of `model` (a faster-whisper name or path) on
-    `dataset` scored by the current metrics, or None."""
+def latest(model: str, dataset: str, mode: str = "offline", beam: int = 5) -> dict | None:
+    """The newest saved run of `model` (a faster-whisper name or path) at
+    beam width `beam` on `dataset` scored by the current metrics, or None."""
     runs = learn_dir() / "runs"
-    want = f"faster-whisper:{model}"
+    want = f"faster-whisper:{model}" + (f"@beam{beam}" if beam != 5 else "")
     for path in sorted(runs.glob("eval-*.json"), reverse=True) if runs.exists() else []:
         try:
             data = json.loads(path.read_text())
@@ -173,6 +173,9 @@ def latest(model: str, dataset: str, mode: str = "offline") -> dict | None:
     return None
 
 
+# Fewer held-out clips than this can't tell a better model from luck.
+MIN_EVAL_CLIPS = 5
+
 # A fine-tune may trade a hair of WER for vocabulary; it may not regress either.
 WER_SLACK = 0.002
 
@@ -196,7 +199,10 @@ def paired(candidate: dict, current: dict, *, n_boot: int = 2000) -> dict | None
 
 
 def promotion_verdict(candidate: dict, current: dict) -> tuple[bool, str]:
-    """Is `candidate` at least as good as `current` on the same clips?"""
+    """Is `candidate` at least as good as `current` on the same clips?
+
+    No verdict without evidence: too few clips, different clips, or a clip
+    the candidate failed to decode at all (a crashed decode scores 0% WER)."""
     rows = [("WER", current["wer"], candidate["wer"], "{:.1%}"),
             ("vocab recall", current["term_recall"], candidate["term_recall"], "{:.1%}"),
             ("loops", current["repetitions"], candidate["repetitions"], "{}")]
@@ -208,6 +214,10 @@ def promotion_verdict(candidate: dict, current: dict) -> tuple[bool, str]:
                   f"WER change {p['mean']:+.1%} (90% interval {p['lo']:+.1%} … {p['hi']:+.1%})")
         if p["lo"] < 0 < p["hi"]:
             table += "\n  (the interval spans zero: the WER difference may be luck)"
+    clips = candidate.get("clips", 0)
+    if candidate.get("failures", 0) or clips != current.get("clips", 0) or clips < MIN_EVAL_CLIPS:
+        return False, table + (f"\n  not enough evidence: {clips} clips "
+                               f"({candidate.get('failures', 0)} failed) vs {current.get('clips', 0)}")
     ok = (candidate["wer"] <= current["wer"] + WER_SLACK
           and candidate["term_recall"] >= current["term_recall"]
           and candidate["repetitions"] <= current["repetitions"])

voiceio/learn/quiet.py

@@ -0,0 +1,54 @@
+"""Is the machine quiet enough for background learning?
+
+Nightly learning is CPU-heavy for an hour or more. It runs at idle priority
+regardless, but it should not even start while the machine is busy or on
+battery: a laptop running on battery at 3am would just drain.
+"""
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+POWER_SUPPLY = Path("/sys/class/power_supply")
+
+
+def on_battery(root: Path = POWER_SUPPLY) -> bool:
+    """True when the machine has mains supplies and none is online."""
+    mains = []
+    for supply in root.glob("*"):
+        try:
+            if (supply / "type").read_text().strip() == "Mains":
+                mains.append((supply / "online").read_text().strip() == "1")
+        except OSError:
+            continue
+    return bool(mains) and not any(mains)
+
+
+def busy_reason(max_load: float) -> str | None:
+    """Why learning should wait right now, or None when the machine is quiet."""
+    load = os.getloadavg()[0] / (os.cpu_count() or 1)
+    if load > max_load:
+        return f"busy (load {load:.2f} per CPU, waiting for {max_load:g})"
+    if on_battery():
+        return "on battery"
+    return None
+
+
+def wait_until_quiet(max_load: float, wait_hours: float, *, poll: float = 300,
+                     sleep: Callable[[float], None] = time.sleep,
+                     clock: Callable[[], float] = time.monotonic,
+                     say: Callable[[str], None] = print) -> bool:
+    """Block until the machine is quiet. False when it stayed busy for wait_hours."""
+    deadline = clock() + wait_hours * 3600
+    last = None
+    while (reason := busy_reason(max_load)) is not None:
+        if reason != last:
+            say(f"waiting: {reason}")
+            last = reason
+        if clock() + poll > deadline:
+            say(f"still {reason} after {wait_hours:g} h; trying again at the next scheduled run")
+            return False
+        sleep(poll)
+    return True

voiceio/learn/review.py

@@ -26,8 +26,10 @@ class Item:
     reason: str
 
 
-def _contains(seg_words: list[str], live_words: list[str]) -> bool:
-    """Whether the segment's words occur (nearly) contiguously in the live text."""
+def _contains(seg_words: list[str], live_words: list[str],
+              tolerance: float = _DISAGREE_WER) -> bool:
+    """Whether the segment's words occur (nearly, within `tolerance` of its
+    words) contiguously in the live text."""
     n = len(seg_words)
     if not n:
         return True
@@ -36,7 +38,7 @@ def _contains(seg_words: list[str], live_words: list[str]) -> bool:
         window = live_words[i:i + n]
         match = sum(a == b for a, b in zip(seg_words, window)) / n
         best = max(best, match)
-        if best >= 1 - _DISAGREE_WER:
+        if best >= 1 - tolerance:
             return True
     return False
 
@@ -84,12 +86,31 @@ def live_span(segment_text: str, live: str) -> str | None:
 
 
 def queue_all(clips: list[Clip], labels: dict[str, Label]) -> list[Item]:
-    """Every segment of every unreviewed clip — for building a gold test set,
-    where a reference is only trustworthy if all of it was checked."""
-    return [Item(clip, labels[clip.audio], i, "test set")
-            for clip in clips
-            if clip.audio in labels and not labels[clip.audio].reviewed
-            for i in range(len(labels[clip.audio].segments))]
+    """Segments to check for a gold test set, cheapest clips first.
+
+    A reference is only trustworthy if all of it was checked — but where the
+    teacher and the live decode agree word for word, two independent models
+    already did; those segments are kept as they are, and only the rest are
+    asked. Clips needing the fewest answers come first, so each minute of
+    review completes as many gold clips as possible. A clip with no live
+    decode (an import) has every segment asked; one where everything agrees
+    asks nothing and stays a teacher label.
+    """
+    per_clip: list[list[Item]] = []
+    for clip in clips:
+        lab = labels.get(clip.audio)
+        if lab is None or lab.reviewed:
+            continue
+        live = metrics.words(clip.raw)
+        items = [Item(clip, lab, i, "test set: teacher and live disagree" if live else "test set")
+                 for i, seg in enumerate(lab.segments)
+                 # Word for word: a gold reference can't skip "kalchi" vs
+                 # "Kalshi" in an otherwise matching sentence.
+                 if not live or not _contains(metrics.words(seg.text), live, tolerance=0.0)]
+        if items:
+            per_clip.append(items)
+    per_clip.sort(key=len)
+    return [it for items in per_clip for it in items]
 
 
 def run(items: list[Item], *, ask: Callable[[Item], str | None],

voiceio/pidlock.py

@@ -20,3 +20,21 @@ def lock_pid_file(fd) -> None:
         import fcntl
         fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
         log.debug("PID lock acquired (fcntl)")
+
+
+def daemon_alive(path) -> bool:
+    """Whether a voiceio daemon holds the PID lock at `path` (probes without
+    keeping the lock, and without truncating the file)."""
+    if sys.platform == "win32":
+        return True     # no cheap probe; callers then trust their other signal
+    import fcntl
+    try:
+        with open(path, "a") as fd:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                return True
+            fcntl.flock(fd, fcntl.LOCK_UN)
+            return False
+    except OSError:
+        return False

voiceio/service.py

@@ -86,8 +86,25 @@ WantedBy=graphical-session.target
 """
 
 
-def _learn_units(bin_path: str) -> tuple[str, str]:
-    """(service, timer) for nightly learning on this machine."""
+LEARN_EVERY = {"day": "*-*-*", "week": "Sun *-*-*"}
+
+
+def learn_calendar(at: str, every: str) -> str:
+    """systemd OnCalendar for `[learn] at` / `every`; ValueError when invalid."""
+    import re
+    if every not in LEARN_EVERY:
+        raise ValueError(f"every must be one of {', '.join(LEARN_EVERY)}, not {every!r}")
+    m = re.fullmatch(r"([01]?\d|2[0-3]):([0-5]\d)", at.strip())
+    if not m:
+        raise ValueError(f"at must be a time like 03:30, not {at!r}")
+    return f"{LEARN_EVERY[every]} {int(m[1]):02d}:{m[2]}"
+
+
+def _learn_units(bin_path: str, auto_promote: bool = False,
+                 calendar: str = "*-*-* 03:30") -> tuple[str, str]:
+    """(service, timer) for scheduled learning on this machine."""
+    # --when-idle: wait for a quiet machine on mains power before starting.
+    flags = " --when-idle" + (" --auto-promote" if auto_promote else "")
     service = f"""\
 [Unit]
 Description=VoiceIO - learn from today's dictation (label, retrain when enough is new)
@@ -95,7 +112,7 @@ Documentation=https://github.com/Hugo0/voiceio#make-it-yours
 
 [Service]
 Type=oneshot
-ExecStart={bin_path} learn maintain
+ExecStart={bin_path} learn maintain{flags}
 # Background work: it gets the CPU only when nothing else wants it, so
 # dictation and everything else stay fast. The unit's own cgroup already
 # does what `learn` would otherwise re-exec into a scope for.
@@ -104,14 +121,14 @@ IOWeight=10
 Nice=19
 Environment=VOICEIO_IDLE_SCOPE=1 PYTHONUNBUFFERED=1
 """
-    timer = """\
+    timer = f"""\
 [Unit]
-Description=VoiceIO - nightly learning
+Description=VoiceIO - scheduled learning
 
 [Timer]
-OnCalendar=*-*-* 03:30
-RandomizedDelaySec=30min
-# A laptop that was asleep at 03:30 catches up when it next runs.
+OnCalendar={calendar}
+RandomizedDelaySec=15min
+# A laptop that was asleep at that time catches up when it next runs.
 Persistent=true
 
 [Install]
@@ -128,11 +145,15 @@ def _systemctl(*args: str) -> bool:
         return False
 
 
-def install_learn_timer() -> bool:
-    """Run `voiceio learn maintain` nightly. True when the timer is enabled."""
+def install_learn_timer(auto_promote: bool = False) -> bool:
+    """Run `voiceio learn maintain` on the `[learn]` schedule. True when the
+    timer is enabled."""
     if _IS_WINDOWS or not has_systemd():
         return False
-    service, timer = _learn_units(_find_voiceio_bin())
+    from voiceio import config
+    learn = config.load().learn
+    service, timer = _learn_units(_find_voiceio_bin(), auto_promote,
+                                  learn_calendar(learn.at, learn.every))
     SERVICE_DIR.mkdir(parents=True, exist_ok=True)
     LEARN_SERVICE_PATH.write_text(service)
     LEARN_TIMER_PATH.write_text(timer)
@@ -151,6 +172,39 @@ def learn_timer_enabled() -> bool:
     return LEARN_TIMER_PATH.exists() and _systemctl("is-enabled", "--quiet", LEARN_TIMER_NAME)
 
 
+def learning_now() -> bool:
+    return _systemctl("is-active", "--quiet", LEARN_SERVICE_NAME)
+
+
+def stop_learning() -> bool:
+    """Stop a scheduled learning run, training included (its whole cgroup)."""
+    return _systemctl("stop", LEARN_SERVICE_NAME)
+
+
+def learn_schedule_summary() -> str:
+    """'off', or e.g. 'daily at 03:30 (auto-promote)'."""
+    if not learn_timer_enabled():
+        return "off"
+    from voiceio import config
+    learn = config.load().learn
+    when = ("weekly on Sunday" if learn.every == "week" else "daily") + f" at {learn.at}"
+    return when + (" (auto-promote)" if learn_timer_auto_promotes() else "")
+
+
+def learn_timer_auto_promotes() -> bool:
+    try:
+        return "--auto-promote" in LEARN_SERVICE_PATH.read_text()
+    except OSError:
+        return False
+
+
+def restart_when_idle() -> bool:
+    """Restart the daemon once no dictation is in progress. False when it
+    stayed busy (never cut a dictation off) or the restart failed."""
+    from voiceio.cli.servicecmd import wait_until_idle
+    return wait_until_idle() and _systemctl("restart", SERVICE_NAME)
+
+
 def uninstall_correct_timer() -> None:
     """Remove the pre-1.0 weekly cloud-mining timer (`correct --auto --batch`).
     It is gone in 1.0: mining moved to the local, opt-in `voiceio learn`."""