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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.4.0
+Version: 1.5.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -190,7 +190,7 @@ voiceio learn eval       # score the current model on your held-out clips: WER a
                          #   --streaming replays them through live dictation and times stop→text
 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 maintain   # later: label what's new, and once 50+ clips piled up ([learn] min_new), retrain and compare
 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
@@ -199,6 +199,8 @@ 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**.
 
+What a scheduled run trains comes from `[learn]` too: `base` (default `small`; any Whisper size, `.en` included, or a Hugging Face checkpoint), `teacher` (default `large-v3-turbo`), `epochs` (4) and `min_new` (50); `maintain`'s flags override them. To fine-tune the English-only medium model: `voiceio config set learn.base medium.en` (on CPU, medium trains and dictates roughly three times slower than small).
+
 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`.
@@ -315,6 +317,11 @@ Logs: `journalctl --user -u voiceio` or `~/.local/state/voiceio/voiceio.log`.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the architecture, conventions and the reasoning behind the model choice. Please open an issue before a large PR.
 
+## Credits
+
+- Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models. The in-browser demo on [voiceio.dev](https://voiceio.dev) runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).
+- The landing page's look (dithered art, typewriter heading, hairline bento) takes its inspiration from Romario Kavin's [KOLlateral](https://github.com/RomarioKavin1/kollateral).
+
 ## License
 
 MIT. Model weights are not part of voiceio and carry their own licenses (see [Choose a model](#choose-a-model)).

{python_voiceio-1.4.0 → python_voiceio-1.5.0}/README.md

@@ -137,7 +137,7 @@ voiceio learn eval       # score the current model on your held-out clips: WER a
                          #   --streaming replays them through live dictation and times stop→text
 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 maintain   # later: label what's new, and once 50+ clips piled up ([learn] min_new), retrain and compare
 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
@@ -146,6 +146,8 @@ 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**.
 
+What a scheduled run trains comes from `[learn]` too: `base` (default `small`; any Whisper size, `.en` included, or a Hugging Face checkpoint), `teacher` (default `large-v3-turbo`), `epochs` (4) and `min_new` (50); `maintain`'s flags override them. To fine-tune the English-only medium model: `voiceio config set learn.base medium.en` (on CPU, medium trains and dictates roughly three times slower than small).
+
 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`.
@@ -262,6 +264,11 @@ Logs: `journalctl --user -u voiceio` or `~/.local/state/voiceio/voiceio.log`.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the architecture, conventions and the reasoning behind the model choice. Please open an issue before a large PR.
 
+## Credits
+
+- Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models. The in-browser demo on [voiceio.dev](https://voiceio.dev) runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).
+- The landing page's look (dithered art, typewriter heading, hairline bento) takes its inspiration from Romario Kavin's [KOLlateral](https://github.com/RomarioKavin1/kollateral).
+
 ## License
 
 MIT. Model weights are not part of voiceio and carry their own licenses (see [Choose a model](#choose-a-model)).

{python_voiceio-1.4.0 → python_voiceio-1.5.0}/pyproject.toml

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.4.0
+Version: 1.5.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
@@ -190,7 +190,7 @@ voiceio learn eval       # score the current model on your held-out clips: WER a
                          #   --streaming replays them through live dictation and times stop→text
 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 maintain   # later: label what's new, and once 50+ clips piled up ([learn] min_new), retrain and compare
 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
@@ -199,6 +199,8 @@ 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**.
 
+What a scheduled run trains comes from `[learn]` too: `base` (default `small`; any Whisper size, `.en` included, or a Hugging Face checkpoint), `teacher` (default `large-v3-turbo`), `epochs` (4) and `min_new` (50); `maintain`'s flags override them. To fine-tune the English-only medium model: `voiceio config set learn.base medium.en` (on CPU, medium trains and dictates roughly three times slower than small).
+
 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`.
@@ -315,6 +317,11 @@ Logs: `journalctl --user -u voiceio` or `~/.local/state/voiceio/voiceio.log`.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the architecture, conventions and the reasoning behind the model choice. Please open an issue before a large PR.
 
+## Credits
+
+- Speech recognition: [faster-whisper](https://github.com/SYSTRAN/faster-whisper) and [CTranslate2](https://github.com/OpenNMT/CTranslate2), with OpenAI's [Whisper](https://github.com/openai/whisper) models. The in-browser demo on [voiceio.dev](https://voiceio.dev) runs [Moonshine](https://github.com/usefulsensors/moonshine) through [transformers.js](https://github.com/huggingface/transformers.js).
+- The landing page's look (dithered art, typewriter heading, hairline bento) takes its inspiration from Romario Kavin's [KOLlateral](https://github.com/RomarioKavin1/kollateral).
+
 ## License
 
 MIT. Model weights are not part of voiceio and carry their own licenses (see [Choose a model](#choose-a-model)).

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

@@ -383,3 +383,105 @@ def test_promote_and_rollback_run_on_promote_with_the_model(monkeypatch, tmp_pat
     cli.cmd_promote(argparse.Namespace(run="v0002-small-x", force=True))
     cli.cmd_rollback(argparse.Namespace())
     assert out.read_text().split() == [str(run), "small"]
+
+
+def _maintain_calls(monkeypatch, min_new_clips: int = 3) -> dict:
+    """Run-ready maintain with labeling/training/eval faked; records what they got."""
+    from types import SimpleNamespace
+
+    from voiceio.cli import learn as cli
+    for i in range(min_new_clips):
+        _clip(f"{i}.wav", 3, "x")
+        store.add_label(f"{i}.wav", [Segment(0, 3, "hello there")], "teacher:fake")
+    got: dict = {}
+    monkeypatch.setattr(cli, "cmd_label", lambda a: got.update(teacher=a.teacher))
+    monkeypatch.setattr(cli, "_announce_learning", lambda min_new: got.update(announced=min_new))
+    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 ds, **k: got.update(k) or store.learn_dir() / "r")
+    monkeypatch.setattr(evaluate, "promotion_verdict", lambda c, b: (False, "table"))
+    return got
+
+
+def _learn_config(**values) -> None:
+    for key, value in values.items():
+        config.set_value("learn", key, value)
+
+
+def test_maintain_trains_what_learn_config_says(monkeypatch):
+    import argparse
+
+    from voiceio.cli import learn as cli
+    _learn_config(base="medium.en", teacher="large-v3", epochs=2, min_new=3)
+    got = _maintain_calls(monkeypatch)
+    cli.cmd_maintain(argparse.Namespace(min_new=None, base=None, epochs=None))
+    assert got == {"teacher": "large-v3", "announced": 3, "base": "medium.en", "epochs": 2}
+
+
+def test_maintain_config_min_new_gates_retraining(monkeypatch, capsys):
+    import argparse
+
+    from voiceio.cli import learn as cli
+    _learn_config(min_new=4)
+    got = _maintain_calls(monkeypatch)
+    cli.cmd_maintain(argparse.Namespace(min_new=None, base=None, epochs=None))
+    assert "base" not in got and "retraining waits for 4" in capsys.readouterr().out
+    assert got["teacher"] is None                     # empty: the default teacher
+
+
+def test_maintain_flags_override_learn_config(monkeypatch):
+    import argparse
+
+    from voiceio.cli import learn as cli
+    _learn_config(base="medium.en", epochs=2, min_new=100)
+    got = _maintain_calls(monkeypatch)
+    cli.cmd_maintain(argparse.Namespace(min_new=3, base="tiny", epochs=7))
+    assert (got["announced"], got["base"], got["epochs"]) == (3, "tiny", 7)
+
+
+@pytest.mark.parametrize("values, message", [
+    ({"epochs": 0}, "epochs must be at least 1"),
+    ({"min_new": 0}, "min_new must be at least 1"),
+    ({"base": ""}, "base must name a model"),
+])
+def test_maintain_rejects_bad_learn_config(monkeypatch, values, message):
+    import argparse
+
+    from voiceio.cli import learn as cli
+    _learn_config(**values)
+    got = _maintain_calls(monkeypatch)
+    with pytest.raises(SystemExit, match=message):
+        cli.cmd_maintain(argparse.Namespace(min_new=None, base=None, epochs=None))
+    assert got == {}                                  # refused before any work
+
+
+def test_english_only_base_needs_english(monkeypatch):
+    import argparse
+
+    from voiceio.cli import learn as cli
+    _learn_config(base="small.en")
+    config.set_value("model", "language", "de")
+    _maintain_calls(monkeypatch)
+    with pytest.raises(SystemExit, match="English-only"):
+        cli.cmd_maintain(argparse.Namespace(min_new=None, base=None, epochs=None))
+
+
+def test_english_only_bases_train_without_language_prefix():
+    assert train.HF_BASE["medium.en"] == "openai/whisper-medium.en"
+    cfg = train.TrainConfig(language="en")
+    assert train._prefix(51865, cfg) == {"language": "en", "task": "transcribe"}
+    assert train._prefix(51864, cfg) == {}            # *.en: <|startoftranscript|> only
+
+
+def test_schedule_on_states_the_configured_threshold(monkeypatch, capsys):
+    import argparse
+
+    from voiceio import service
+    from voiceio.cli import learn as cli
+    _learn_config(min_new=20)
+    monkeypatch.setattr(train, "missing_train_deps", lambda: [])
+    monkeypatch.setattr(service, "install_learn_timer", lambda auto_promote: True)
+    monkeypatch.setattr(service, "learn_schedule_summary", lambda: "daily at 03:30")
+    cli.cmd_schedule(argparse.Namespace(state="on", at=None, every=None, auto_promote=False))
+    assert "retrains once 20+ clips are new" in capsys.readouterr().out

python_voiceio-1.5.0/voiceio/__init__.py

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

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

@@ -80,10 +80,10 @@ def register(sub: argparse._SubParsersAction) -> None:
     t.set_defaults(func=cmd_train)
 
     mt = lsub.add_parser("maintain", help="Label new clips; retrain and compare once enough piled up")
-    mt.add_argument("--min-new", type=int, default=50,
-                    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("--min-new", type=int, default=None,
+                    help="new labeled clips needed before retraining (default: [learn] min_new)")
+    mt.add_argument("--base", default=None, help="model to fine-tune (default: [learn] base)")
+    mt.add_argument("--epochs", type=int, default=None, help="default: [learn] epochs")
     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",
@@ -426,7 +426,8 @@ def _train(ds: Path, *, base: str = "small", epochs: int = 4, synthetic_share: f
     folder = store.learn_dir() / "exports" / ds.name
     counts = train.export(ds, folder, extra_train_rows=synth, hotwords=_live_hotwords())
     print(f"exported {counts} windows ({len(synth)} synthetic) to {folder}")
-    run = _models_dir() / f"{ds.name}-{base}-{time.strftime('%Y%m%d-%H%M')}"
+    # A Hugging Face id or path names the run by its last part: one directory.
+    run = _models_dir() / f"{ds.name}-{Path(base).name}-{time.strftime('%Y%m%d-%H%M')}"
     if remote:
         print("\n" + train.remote_recipe(folder, run, base))
         return None
@@ -443,12 +444,12 @@ def cmd_maintain(args: argparse.Namespace) -> None:
     whether the result beats the current model. Never promotes by itself."""
     _yield_cpu()
     from voiceio.learn import evaluate, quiet
-    learn_cfg = _cfg().learn
+    learn_cfg = _maintain_settings(args)
     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))
+    _announce_learning(learn_cfg.min_new)
+    cmd_label(argparse.Namespace(teacher=learn_cfg.teacher or None, limit=None, relabel=False))
     from voiceio.learn import train
     if missing := train.missing_train_deps():
         # Labeling alone is worth it; retraining waits for the extra. Exit 0:
@@ -459,14 +460,14 @@ 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 new < args.min_new:   # the first dataset too: a handful of clips trains nothing
+    if new < learn_cfg.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}.")
+        print(f"{new} new labeled clips{since}; retraining waits for {learn_cfg.min_new}.")
         return
     ds = store.build_dataset()
     print(f"built {ds.name} ({new} new clips)")
     current = _run_eval(None, ds)
-    run = _train(ds, base=args.base, epochs=args.epochs)
+    run = _train(ds, base=learn_cfg.base, epochs=learn_cfg.epochs)
     candidate = _run_eval(str(run / "ct2"), ds)
     ok, table = evaluate.promotion_verdict(_scores(candidate), _scores(current))
     print(f"\n{_cfg().model.name} → {run.name} on {ds.name}:\n{table}")
@@ -498,6 +499,24 @@ def cmd_maintain(args: argparse.Namespace) -> None:
                         urgent=True)
 
 
+def _maintain_settings(args: argparse.Namespace | None = None):
+    """`[learn]` with `maintain`'s flags applied, validated: an unattended run
+    must fail on a bad setting with a message, not deep inside training."""
+    import dataclasses
+    cfg = _cfg()
+    flags = {k: getattr(args, k, None) for k in ("base", "epochs", "min_new")}
+    learn = dataclasses.replace(cfg.learn, **{k: v for k, v in flags.items() if v is not None})
+    if not learn.base.strip():
+        raise SystemExit("[learn] base must name a model to fine-tune, e.g. small")
+    for key in ("epochs", "min_new"):
+        if getattr(learn, key) < 1:
+            raise SystemExit(f"[learn] {key} must be at least 1, not {getattr(learn, key)}")
+    language = cfg.model.language
+    if learn.base.endswith(".en") and language not in ("en", "auto"):
+        raise SystemExit(f"[learn] base {learn.base} is English-only; [model] language is {language}")
+    return learn
+
+
 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
@@ -568,6 +587,7 @@ def cmd_schedule(args: argparse.Namespace) -> None:
             print(f"on, {service.learn_schedule_summary()}")
             return
     if args.state == "on":
+        min_new = _maintain_settings().min_new
         if not config.load().data.retain_audio:
             print("note: [data] retain_audio is off, so there is nothing new to learn from;\n"
                   "      turn it on with: voiceio config set data.retain_audio true")
@@ -581,7 +601,7 @@ def cmd_schedule(args: argparse.Namespace) -> None:
         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 "
+              f"{min_new}+ 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."))

{python_voiceio-1.4.0 → python_voiceio-1.5.0}/voiceio/config.py

@@ -258,6 +258,14 @@ class LearnConfig:
     # at the next scheduled run.
     max_load: float = 0.25
     wait_hours: float = 3.0
+    # What a scheduled run trains (`voiceio learn maintain`'s flags override):
+    # the Whisper size or Hugging Face checkpoint to fine-tune, e.g. "medium.en";
+    # the model that labels new clips (empty: large-v3-turbo); epochs per run;
+    # and how many new labeled clips it waits for before retraining.
+    base: str = "small"
+    teacher: str = ""
+    epochs: int = 4
+    min_new: int = 50
 
 
 @dataclass

{python_voiceio-1.4.0 → python_voiceio-1.5.0}/voiceio/learn/train.py

@@ -42,6 +42,8 @@ HF_BASE = {
     "tiny": "openai/whisper-tiny", "base": "openai/whisper-base",
     "small": "openai/whisper-small", "medium": "openai/whisper-medium",
     "large-v3": "openai/whisper-large-v3", "large-v3-turbo": "openai/whisper-large-v3-turbo",
+    "tiny.en": "openai/whisper-tiny.en", "base.en": "openai/whisper-base.en",
+    "small.en": "openai/whisper-small.en", "medium.en": "openai/whisper-medium.en",
 }
 
 
@@ -195,6 +197,14 @@ def decoder_batch(seqs: list[tuple[list[int], int]], pad: int):
 
 # ── train ────────────────────────────────────────────────────────────────
 
+def _prefix(vocab_size: int, cfg: TrainConfig) -> dict:
+    """Tokenizer prefix matching what faster-whisper feeds at inference. An
+    English-only model (vocabulary < 51865, CTranslate2's own test) is
+    decoded from <|startoftranscript|> alone: training it behind
+    <|en|><|transcribe|> would teach a prefix it never sees."""
+    return {"language": cfg.language, "task": "transcribe"} if vocab_size >= 51865 else {}
+
+
 def lr_schedule(total_steps: int, warmup: float = 0.1):
     """Linear warmup over the first `warmup` share of steps, then linear decay
     to zero — a few hundred steps on a few hours of audio overshoot without."""
@@ -220,8 +230,8 @@ def train(folder: Path, out: Path, cfg: TrainConfig = TrainConfig()) -> Path:
         torch.set_num_threads(max(1, (os.cpu_count() or 2) // 2))
     decoder_only = cfg.decoder_only if cfg.decoder_only is not None else device == "cpu"
     base_id = HF_BASE.get(cfg.base, cfg.base)
-    processor = WhisperProcessor.from_pretrained(base_id, language=cfg.language, task="transcribe")
     model = WhisperForConditionalGeneration.from_pretrained(base_id)
+    processor = WhisperProcessor.from_pretrained(base_id, **_prefix(model.config.vocab_size, cfg))
     model.config.forced_decoder_ids = None
     model = get_peft_model(model, LoraConfig(
         r=cfg.lora_r, lora_alpha=cfg.lora_alpha, lora_dropout=0.05,

python_voiceio-1.4.0/voiceio/__init__.py

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