python-voiceio 1.3.0__tar.gz → 1.4.0__tar.gz

{python_voiceio-1.3.0/python_voiceio.egg-info → python_voiceio-1.4.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.3.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.
 
@@ -191,10 +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
-                            #   (--auto-promote: switch to a winner by itself; `learn rollback` undoes it)
+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.
@@ -302,7 +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.
 - **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.3.0 → python_voiceio-1.4.0}/README.md

@@ -5,7 +5,7 @@
 [![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.
 
@@ -138,10 +138,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
-                            #   (--auto-promote: switch to a winner by itself; `learn rollback` undoes it)
+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.
@@ -249,7 +255,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.
 - **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.3.0 → python_voiceio-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-voiceio"
-version = "1.3.0"
+version = "1.4.0"
 description = "Voice dictation for Linux. Speak → text, locally, instantly."
 readme = "README.md"
 license = "MIT"
@@ -58,7 +58,7 @@ sherpa = ["sherpa-onnx>=1.12"]
 dev = ["pytest>=7.0", "pytest-mock", "ruff>=0.15,<0.18"]
 
 [project.urls]
-Homepage = "https://github.com/Hugo0/voiceio"
+Homepage = "https://voiceio.dev/"
 Repository = "https://github.com/Hugo0/voiceio"
 Issues = "https://github.com/Hugo0/voiceio/issues"
 Changelog = "https://github.com/Hugo0/voiceio/releases"

{python_voiceio-1.3.0 → python_voiceio-1.4.0/python_voiceio.egg-info}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.3.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.
 
@@ -191,10 +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
-                            #   (--auto-promote: switch to a winner by itself; `learn rollback` undoes it)
+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.
@@ -302,7 +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.
 - **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.3.0 → python_voiceio-1.4.0}/python_voiceio.egg-info/SOURCES.txt

@@ -37,6 +37,7 @@ tests/test_learn_clean.py
 tests/test_learn_import.py
 tests/test_learn_metrics.py
 tests/test_learn_pipeline.py
+tests/test_learn_quiet.py
 tests/test_learn_review.py
 tests/test_learn_targets.py
 tests/test_llm.py
@@ -144,6 +145,7 @@ voiceio/learn/clean.py
 voiceio/learn/evaluate.py
 voiceio/learn/importer.py
 voiceio/learn/metrics.py
+voiceio/learn/quiet.py
 voiceio/learn/review.py
 voiceio/learn/store.py
 voiceio/learn/teacher.py

{python_voiceio-1.3.0 → python_voiceio-1.4.0}/tests/test_health.py

@@ -121,5 +121,5 @@ def test_learning_status_and_tips(monkeypatch):
     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 st["Recordings"].startswith("on (") and st["Scheduled learning"] == "off"
     assert any("learn schedule on" in t for t in _accuracy_tips(st))

{python_voiceio-1.3.0 → python_voiceio-1.4.0}/tests/test_learn_pipeline.py

@@ -343,6 +343,7 @@ def test_maintain_auto_promote_switches_restarts_and_says_how_to_undo(monkeypatc
     run = store.learn_dir() / "models" / "v0001-small-x"
     calls = []
     monkeypatch.setattr(cli, "cmd_label", lambda a: None)
+    monkeypatch.setattr(cli, "_announce_learning", lambda min_new: None)
     monkeypatch.setattr(train, "missing_train_deps", lambda: [])
     monkeypatch.setattr(cli, "_run_eval", lambda *a, **k: SimpleNamespace(
         wer=0.1, term_recall=0.5, repetitions=0, per_clip=[]))
@@ -366,3 +367,19 @@ def test_maintain_auto_promote_switches_restarts_and_says_how_to_undo(monkeypatc
     monkeypatch.setattr(cli, "cmd_promote", refuse)
     cli.cmd_maintain(argparse.Namespace(min_new=1, base="small", epochs=1, auto_promote=True))
     assert calls == []
+
+
+def test_promote_and_rollback_run_on_promote_with_the_model(monkeypatch, tmp_path):
+    import argparse
+
+    from voiceio import config
+    from voiceio.cli import learn as cli
+    run = store.learn_dir() / "models" / "v0002-small-x" / "ct2"
+    run.mkdir(parents=True)
+    (run / "model.bin").write_text("")
+    out = tmp_path / "hook.txt"
+    config.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    config.CONFIG_PATH.write_text(f'[learn]\non_promote = "echo $VOICEIO_MODEL >> {out}"\n')
+    cli.cmd_promote(argparse.Namespace(run="v0002-small-x", force=True))
+    cli.cmd_rollback(argparse.Namespace())
+    assert out.read_text().split() == [str(run), "small"]

python_voiceio-1.4.0/tests/test_learn_quiet.py

@@ -0,0 +1,102 @@
+import argparse
+
+from voiceio.learn import quiet
+
+
+def _supply(root, name, kind, online):
+    d = root / name
+    d.mkdir()
+    (d / "type").write_text(kind + "\n")
+    (d / "online").write_text(online + "\n")
+
+
+def test_on_battery_needs_a_mains_supply_that_is_offline(tmp_path):
+    assert not quiet.on_battery(tmp_path)                 # desktop: no supplies listed
+    _supply(tmp_path, "BAT0", "Battery", "0")
+    _supply(tmp_path, "AC", "Mains", "0")
+    assert quiet.on_battery(tmp_path)
+    (tmp_path / "AC" / "online").write_text("1\n")
+    assert not quiet.on_battery(tmp_path)
+
+
+def test_busy_reason_is_load_per_cpu_then_battery(monkeypatch):
+    monkeypatch.setattr(quiet.os, "cpu_count", lambda: 8)
+    monkeypatch.setattr(quiet, "on_battery", lambda: False)
+    monkeypatch.setattr(quiet.os, "getloadavg", lambda: (4.0, 0, 0))     # 0.5 per CPU
+    assert "load 0.50 per CPU" in quiet.busy_reason(0.25)
+    monkeypatch.setattr(quiet.os, "getloadavg", lambda: (1.0, 0, 0))
+    assert quiet.busy_reason(0.25) is None
+    monkeypatch.setattr(quiet, "on_battery", lambda: True)
+    assert quiet.busy_reason(0.25) == "on battery"
+
+
+def test_wait_until_quiet_waits_then_gives_up(monkeypatch):
+    now = [0.0]
+    sleeps = []
+    reasons = iter(["busy", "busy", None])
+    monkeypatch.setattr(quiet, "busy_reason", lambda _: next(reasons))
+    args = dict(poll=300, sleep=lambda s: (sleeps.append(s), now.__setitem__(0, now[0] + s)),
+                clock=lambda: now[0], say=lambda _: None)
+    assert quiet.wait_until_quiet(0.25, 3, **args)
+    assert sleeps == [300, 300]
+
+    monkeypatch.setattr(quiet, "busy_reason", lambda _: "on battery")
+    said = []
+    now[0] = 0.0
+    assert not quiet.wait_until_quiet(0.25, 1, **{**args, "say": said.append})
+    assert now[0] <= 3600 and said[-1].startswith("still on battery after 1 h")
+
+
+def test_scheduled_maintain_waits_for_a_quiet_machine(monkeypatch):
+    from voiceio.cli import learn as cli
+    monkeypatch.setattr(cli, "_yield_cpu", lambda: None)
+    monkeypatch.setattr(quiet, "wait_until_quiet", lambda *a, **k: False)
+    ran = []
+    monkeypatch.setattr(cli, "cmd_label", lambda a: ran.append("label"))
+    cli.cmd_maintain(argparse.Namespace(min_new=5, base="small", epochs=1, when_idle=True))
+    assert ran == []                                      # busy all night: nothing ran
+
+
+def test_learning_announcement_offers_stop_and_weekly(monkeypatch, tmp_path):
+    from voiceio import feedback
+    from voiceio.cli import learn as cli
+    sent = []
+    monkeypatch.setattr(feedback, "notify_actions", lambda *a: sent.append(a))
+    monkeypatch.setattr(cli.store, "load_labels", lambda: {})
+    monkeypatch.setattr(cli.store, "clips", lambda: [argparse.Namespace(audio=f"a{i}.wav") for i in range(3)])
+    monkeypatch.setattr(cli.store, "latest_dataset", lambda: None)
+    cli._announce_learning(min_new=50)
+    (title, body, actions, _), = sent
+    assert "learning" in title and body.startswith("Labeling 3 new recordings,")
+    assert "on this computer" in body and set(actions) == {"stop", "weekly"}
+
+    sent.clear()
+    monkeypatch.setattr(cli.store, "load_labels", lambda: {f"a{i}.wav": 1 for i in range(3)})
+    monkeypatch.setattr(cli.store, "latest_dataset", lambda: tmp_path)
+    monkeypatch.setattr(cli.store, "dataset_clips", lambda _: {f"a{i}.wav" for i in range(3)})
+    cli._announce_learning(min_new=50)
+    assert sent == []                                     # nothing to do: no notification
+
+
+def test_notify_actions_runs_the_picked_action(monkeypatch):
+    import subprocess
+
+    from voiceio import feedback
+    monkeypatch.setattr("sys.platform", "linux")
+    monkeypatch.setattr(feedback, "_which", lambda _: "/usr/bin/notify-send")
+    monkeypatch.setattr(feedback, "_notify_send_has_actions", lambda: True)
+    calls = []
+
+    def fake_run(args, **kw):
+        calls.append(args)
+        return subprocess.CompletedProcess(args, 0, stdout="weekly\n")
+    monkeypatch.setattr(feedback.subprocess, "run", fake_run)
+    picked = []
+
+    class Now:   # run the waiting thread inline
+        def __init__(self, target, daemon): self.target = target
+        def start(self): self.target()
+    monkeypatch.setattr(feedback.threading, "Thread", Now)
+    feedback.notify_actions("t", "b", {"stop": "Stop", "weekly": "Weekly"}, picked.append)
+    assert picked == ["weekly"]
+    assert "--wait" in calls[0] and "--action=stop=Stop" in calls[0]

{python_voiceio-1.3.0 → python_voiceio-1.4.0}/tests/test_service.py

@@ -36,7 +36,7 @@ def test_learn_timer_runs_maintain_at_idle_priority(monkeypatch, tmp_path):
 
     assert service.install_learn_timer()
     unit = service.LEARN_SERVICE_PATH.read_text()
-    assert "ExecStart=/opt/v/bin/voiceio learn maintain" in unit
+    assert "ExecStart=/opt/v/bin/voiceio learn maintain --when-idle" in unit
     assert "CPUWeight=idle" in unit and "VOICEIO_IDLE_SCOPE=1" in unit
     assert "Persistent=true" in service.LEARN_TIMER_PATH.read_text()
     assert ("enable", "--now", service.LEARN_TIMER_NAME) in calls
@@ -89,5 +89,28 @@ def test_learn_timer_auto_promote_is_opt_in(monkeypatch, tmp_path):
     service.install_learn_timer()
     assert not service.learn_timer_auto_promotes()
     service.install_learn_timer(auto_promote=True)
-    assert "learn maintain --auto-promote" in service.LEARN_SERVICE_PATH.read_text()
+    assert "learn maintain --when-idle --auto-promote" in service.LEARN_SERVICE_PATH.read_text()
     assert service.learn_timer_auto_promotes()
+
+
+def test_learn_schedule_comes_from_config(monkeypatch, tmp_path):
+    import pytest
+
+    from voiceio import config
+    monkeypatch.setattr(service, "has_systemd", lambda: True)
+    monkeypatch.setattr(service, "_systemctl", lambda *a: True)
+    monkeypatch.setattr(service, "_find_voiceio_bin", lambda: "voiceio")
+    monkeypatch.setattr(service, "LEARN_SERVICE_PATH", tmp_path / "s.service")
+    monkeypatch.setattr(service, "LEARN_TIMER_PATH", tmp_path / "s.timer")
+    service.install_learn_timer()
+    assert "OnCalendar=*-*-* 03:30" in service.LEARN_TIMER_PATH.read_text()
+
+    config.set_value("learn", "at", "2:05")
+    config.set_value("learn", "every", "week")
+    service.install_learn_timer()
+    assert "OnCalendar=Sun *-*-* 02:05" in service.LEARN_TIMER_PATH.read_text()
+    assert service.learn_schedule_summary() == "weekly on Sunday at 2:05"
+
+    for at, every in (("25:00", "day"), ("3pm", "day"), ("03:30", "month")):
+        with pytest.raises(ValueError):
+            service.learn_calendar(at, every)

python_voiceio-1.4.0/voiceio/__init__.py

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

{python_voiceio-1.3.0 → python_voiceio-1.4.0}/voiceio/cli/learn.py

@@ -86,14 +86,23 @@ def register(sub: argparse._SubParsersAction) -> None:
     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",
@@ -433,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():
@@ -484,15 +498,75 @@ def cmd_maintain(args: argparse.Namespace) -> None:
                         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
-    if not service.learn_timer_enabled():
-        return "off (voiceio learn schedule on)"
-    return "on (auto-promote)" if service.learn_timer_auto_promotes() else "on"
+    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"
@@ -503,8 +577,11 @@ def cmd_schedule(args: argparse.Namespace) -> None:
                   f"      to also retrain: {train.TRAIN_HINT}")
         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 "
+        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."))
@@ -532,6 +609,28 @@ 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:
@@ -563,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"])

{python_voiceio-1.3.0 → python_voiceio-1.4.0}/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", {})),
     )
 
 

{python_voiceio-1.3.0 → python_voiceio-1.4.0}/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

{python_voiceio-1.3.0 → python_voiceio-1.4.0}/voiceio/health.py

@@ -247,8 +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"] = ("off" if not service.learn_timer_enabled() else
-                               "on (auto-promote)" if service.learn_timer_auto_promotes() else "on")
+    out["Scheduled learning"] = service.learn_schedule_summary()
     return out
 
 
@@ -354,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