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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.2.0
+Version: 1.3.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -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
@@ -191,6 +192,7 @@ voiceio learn train      # LoRA fine-tune (needs the `train` extra; decoder-only
 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)
 ```
 
 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`.
@@ -301,7 +303,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 → python_voiceio-1.3.0}/README.md

@@ -129,7 +129,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
@@ -138,6 +139,7 @@ voiceio learn train      # LoRA fine-tune (needs the `train` extra; decoder-only
 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)
 ```
 
 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`.
@@ -248,7 +250,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 → python_voiceio-1.3.0}/pyproject.toml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.2.0
+Version: 1.3.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -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
@@ -191,6 +192,7 @@ voiceio learn train      # LoRA fine-tune (needs the `train` extra; decoder-only
 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)
 ```
 
 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`.
@@ -301,7 +303,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 → python_voiceio-1.3.0}/tests/test_learn_pipeline.py

@@ -132,14 +132,34 @@ def test_learn_jobs_reexec_into_an_idle_scope(monkeypatch):
 
 
 def test_promotion_requires_a_winning_eval():
-    base = {"wer": 0.10, "term_recall": 0.40, "repetitions": 0}
-    better = {"wer": 0.101, "term_recall": 0.70, "repetitions": 0}   # vocab win, WER within slack
-    worse = {"wer": 0.13, "term_recall": 0.70, "repetitions": 0}
+    base = {"wer": 0.10, "term_recall": 0.40, "repetitions": 0, "clips": 44}
+    better = {"wer": 0.101, "term_recall": 0.70, "repetitions": 0, "clips": 44}   # vocab win
+    worse = {"wer": 0.13, "term_recall": 0.70, "repetitions": 0, "clips": 44}
     assert evaluate.promotion_verdict(better, base)[0]
     assert not evaluate.promotion_verdict(worse, base)[0]
     assert not evaluate.promotion_verdict({**better, "repetitions": 2}, base)[0]
 
 
+def test_no_promotion_without_evidence():
+    """A crashed decode scores 0% WER; an empty test split scores nothing."""
+    base = {"wer": 0.10, "term_recall": 0.40, "repetitions": 0, "clips": 44}
+    perfect = {"wer": 0.0, "term_recall": 1.0, "repetitions": 0}
+    assert not evaluate.promotion_verdict({**perfect, "clips": 44, "failures": 3}, base)[0]
+    assert not evaluate.promotion_verdict({**perfect, "clips": 40}, base)[0]      # other clips
+    assert not evaluate.promotion_verdict({**perfect, "clips": 2}, {**base, "clips": 2})[0]
+
+
+def test_latest_finds_runs_at_the_configured_beam():
+    runs = store.learn_dir() / "runs"
+    runs.mkdir(parents=True)
+    for i, (dec, wer) in enumerate([("faster-whisper:small", 5), ("faster-whisper:small@beam2+draft", 2)]):
+        (runs / f"eval-2026010{i}.json").write_text(json.dumps(
+            {"decoder": dec, "dataset": "v0001", "wer": wer, "metrics": metrics.METRICS_VERSION}))
+    assert evaluate.latest("small", "v0001")["wer"] == 5
+    assert evaluate.latest("small", "v0001", beam=2)["wer"] == 2
+    assert evaluate.latest("small", "v0001", beam=1) is None
+
+
 def test_latest_eval_matches_model_dataset_and_mode():
     runs = store.learn_dir() / "runs"
     runs.mkdir(parents=True)
@@ -308,3 +328,41 @@ def test_wait_summary_p90_never_exceeds_max():
     s = r.wait_summary()
     p90 = float(s.split("p90 ")[1].split("s")[0])
     assert p90 <= 6.83
+
+
+def test_maintain_auto_promote_switches_restarts_and_says_how_to_undo(monkeypatch):
+    import argparse
+    from types import SimpleNamespace
+
+    from voiceio import feedback, service
+    from voiceio.cli import learn as cli
+    from voiceio.learn import evaluate
+    for i in range(3):
+        _clip(f"{i}.wav", 3, "x")
+        store.add_label(f"{i}.wav", [Segment(0, 3, "hello there")], "teacher:fake")
+    run = store.learn_dir() / "models" / "v0001-small-x"
+    calls = []
+    monkeypatch.setattr(cli, "cmd_label", lambda a: 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=[]))
+    monkeypatch.setattr(cli, "_train", lambda *a, **k: run)
+    monkeypatch.setattr(evaluate, "promotion_verdict", lambda c, b: (True, "table"))
+    monkeypatch.setattr(cli, "cmd_promote", lambda a: calls.append(("promote", a.run)))
+    monkeypatch.setattr(service, "is_installed", lambda: True)
+    monkeypatch.setattr(service, "restart_when_idle", lambda: calls.append(("restart",)) or True)
+    monkeypatch.setattr(feedback, "notify", lambda t, b, urgent=False: calls.append(("notify", b)))
+
+    cli.cmd_maintain(argparse.Namespace(min_new=1, base="small", epochs=1, auto_promote=True))
+    assert calls[:2] == [("promote", "v0001-small-x"), ("restart",)]
+    assert "voiceio learn rollback" in calls[2][1]
+
+    # The gate's own re-check refuses: no restart, no "switched" notification,
+    # and no crash (the nightly unit must not fail).
+    calls.clear()
+
+    def refuse(a):
+        raise SystemExit("evaluate both models first")
+    monkeypatch.setattr(cli, "cmd_promote", refuse)
+    cli.cmd_maintain(argparse.Namespace(min_new=1, base="small", epochs=1, auto_promote=True))
+    assert calls == []

python_voiceio-1.3.0/tests/test_learn_review.py

@@ -0,0 +1,44 @@
+
+
+def test_queue_all_covers_every_segment_of_unreviewed_clips():
+    from voiceio.learn import review
+    from voiceio.learn.store import Clip, Label, Segment
+    a = Clip("a.wav", 0, 4, "", "")
+    b = Clip("b.wav", 0, 4, "", "")
+    segs = (Segment(0, 2, "one"), Segment(2, 4, "two"))
+    labels = {"a.wav": Label("a.wav", segs, "teacher:x", 0),
+              "b.wav": Label("b.wav", segs, "human", 0)}
+    items = review.queue_all([a, b], labels)
+    assert [(i.clip.audio, i.index) for i in items] == [("a.wav", 0), ("a.wav", 1)]
+
+
+def test_live_span_shows_the_live_decode_only_where_it_differs():
+    from voiceio.learn.review import live_span
+    live = "okay so we use kalchi daily and then more stuff"
+    assert live_span("We use Kalshi daily.", live) == "we use kalchi daily"
+    assert live_span("We use Kalshi daily.", "so we use Kalshi daily ok") is None
+    assert live_span("totally different words here", "nothing alike at all") is None
+
+
+def test_gold_review_asks_only_where_the_models_disagree_cheapest_clip_first():
+    from voiceio.learn import review
+    from voiceio.learn.store import Clip, Label, Segment
+    segs = (Segment(0, 2, "we use Kalshi daily"), Segment(2, 4, "ship it today"))
+    two = Clip("two.wav", 0, 4, "we use kalchi daily ship it to day", "")
+    one = Clip("one.wav", 0, 4, "we use kalchi daily ship it today", "")
+    agree = Clip("agree.wav", 0, 4, "we use Kalshi daily ship it today", "")
+    labels = {c.audio: Label(c.audio, segs, "teacher:x", 0) for c in (two, one, agree)}
+    items = review.queue_all([two, one, agree], labels)
+    assert [(i.clip.audio, i.index) for i in items] == [
+        ("one.wav", 0),                       # one answer completes a gold clip
+        ("two.wav", 0), ("two.wav", 1),
+    ]                                         # agree.wav: nothing to ask
+
+
+def test_gold_review_counts_one_misheard_term_as_disagreement():
+    from voiceio.learn import review
+    from voiceio.learn.store import Clip, Label, Segment
+    segs = (Segment(0, 4, "we ship the Kalshi bot every single day"),)
+    clip = Clip("a.wav", 0, 4, "we ship the kalchi bot every single day", "")
+    items = review.queue_all([clip], {"a.wav": Label("a.wav", segs, "teacher:x", 0)})
+    assert len(items) == 1

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

@@ -48,15 +48,46 @@ def test_learn_timer_runs_maintain_at_idle_priority(monkeypatch, tmp_path):
 def test_daemon_publishes_state_and_restart_waits_for_idle(monkeypatch):
     import threading
 
-    from voiceio import config
+    from voiceio import config, pidlock
     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                      # not the lock holder:
+    assert not config.STATE_PATH.exists()              # says nothing
+    vio._publishes_state = True
     vio._state = _State.RECORDING
     assert config.STATE_PATH.read_text() == "recording"
+
+    monkeypatch.setattr(pidlock, "daemon_alive", lambda path: False)
+    assert wait_until_idle(timeout=5)                  # dead daemon: stale file, no wait
+    monkeypatch.setattr(pidlock, "daemon_alive", lambda path: True)
     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
+    assert wait_until_idle(timeout=5, poll=0.05)       # waited for the dictation
+    vio._state = _State.FINALIZING                     # a hung finalize: short budget
+    assert not wait_until_idle(timeout=60, poll=0.05, finalizing_timeout=0.2)
+
+
+def test_daemon_alive_probes_the_pid_lock(tmp_path):
+    import fcntl
+
+    from voiceio.pidlock import daemon_alive
+    path = tmp_path / "voiceio.pid"
+    assert not daemon_alive(path)
+    with open(path, "a") as held:
+        fcntl.flock(held, fcntl.LOCK_EX)
+        assert daemon_alive(path)
+    assert not daemon_alive(path)
+
+
+def test_learn_timer_auto_promote_is_opt_in(monkeypatch, tmp_path):
+    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 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 service.learn_timer_auto_promotes()

python_voiceio-1.3.0/voiceio/__init__.py

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

{python_voiceio-1.2.0 → python_voiceio-1.3.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()
 

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

@@ -84,10 +84,14 @@ 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.set_defaults(func=cmd_maintain)
 
     sc = lsub.add_parser("schedule", help="Run `maintain` every night (systemd timer)")
     sc.add_argument("state", nargs="?", choices=("on", "off"), help="omit to show")
+    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)
 
     pr = lsub.add_parser("promote", help="Use a trained model for dictation")
@@ -182,8 +186,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 +200,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:")
@@ -442,8 +445,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,13 +458,39 @@ 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 _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"
+
+
 def cmd_schedule(args: argparse.Namespace) -> None:
     from voiceio import config, service
     if args.state == "on":
@@ -471,16 +501,18 @@ 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.")
+              "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:
@@ -506,16 +538,16 @@ 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)")

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

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

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

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

{python_voiceio-1.2.0 → python_voiceio-1.3.0}/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],