python-voiceio 1.8.2__tar.gz → 1.9.0__tar.gz

{python_voiceio-1.8.2/python_voiceio.egg-info → python_voiceio-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.8.2
+Version: 1.9.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT

{python_voiceio-1.8.2 → python_voiceio-1.9.0}/pyproject.toml

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

{python_voiceio-1.8.2 → python_voiceio-1.9.0/python_voiceio.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 1.8.2
+Version: 1.9.0
 Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT

{python_voiceio-1.8.2 → python_voiceio-1.9.0}/python_voiceio.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ tests/test_clipboard_typer.py
 tests/test_commands.py
 tests/test_concurrency_lockdown.py
 tests/test_config.py
+tests/test_context_terms.py
 tests/test_corrections.py
 tests/test_decoders.py
 tests/test_engine.py
@@ -41,6 +42,7 @@ tests/test_ibus_typer.py
 tests/test_idle_audio.py
 tests/test_learn_clean.py
 tests/test_learn_import.py
+tests/test_learn_language.py
 tests/test_learn_metrics.py
 tests/test_learn_pipeline.py
 tests/test_learn_quiet.py
@@ -84,6 +86,7 @@ voiceio/clipboard_read.py
 voiceio/commands.py
 voiceio/config.py
 voiceio/consent.py
+voiceio/context_terms.py
 voiceio/corrections.py
 voiceio/demo.py
 voiceio/display.py

{python_voiceio-1.8.2 → python_voiceio-1.9.0}/tests/test_cancel.py

@@ -156,14 +156,17 @@ def test_cancel_too_late_changes_nothing(tmp_path):
     session = MagicMock()
     session.cancel.return_value = False          # final text already typed
     session.stop.side_effect = lambda audio: (in_stop.set(), release.wait(5), "words")[2]
+    # The finalizer goes on to copy the text from its own thread; left real, it
+    # lands on whatever clipboard a later test has patched in.
+    vio._copy_result_async = MagicMock()
     _finalizing(vio, tmp_path, session)
     assert in_stop.wait(5)
     gen = vio._generation
     vio.cancel()
     assert vio._state == _State.FINALIZING and vio._generation == gen
     release.set()
-    for _ in range(200):
-        if vio._state == _State.IDLE:
+    for _ in range(500):
+        if vio._state == _State.IDLE and not vio._outputs:
             break
         time.sleep(0.01)
     vio.engine.commit.assert_called_once()

python_voiceio-1.9.0/tests/test_context_terms.py

@@ -0,0 +1,253 @@
+"""On-screen vocabulary: term extraction, budget share, capture deadline, and
+that capture never sits on the hotkey path."""
+from __future__ import annotations
+
+import threading
+import time
+from unittest.mock import patch
+
+import pytest
+
+from voiceio import context_terms
+from voiceio.context_terms import ScreenContext, capture, extract_terms
+from voiceio.core.bias import SCREEN_TOKEN_SHARE, BiasProvider
+from voiceio.core.decoders.base import BiasMode, Capabilities
+from voiceio.tokens import count_tokens
+
+HOTWORDS = Capabilities(bias=BiasMode.HOTWORDS | BiasMode.PROMPT, max_bias_tokens=120)
+
+
+# ── extraction ────────────────────────────────────────────────────────────
+
+
+class TestExtract:
+    def test_rare_names_camelcase_acronyms(self):
+        terms = extract_terms(["Kalshi pricing - Discord",
+                               "The HyperNEAT paper uses OpenRouter and the OKR doc."])
+        assert {"Kalshi", "HyperNEAT", "OpenRouter", "OKR"} <= set(terms)
+
+    def test_common_words_and_app_names_are_not_terms(self):
+        terms = extract_terms(["Inbox - Google Chrome",
+                               "Please check the API before the meeting with Hugo."])
+        assert terms == []
+
+    def test_multiword_name_but_not_a_greeting(self):
+        terms = extract_terms(["", "Hey Kosh, ask Tarrant Fnordwick about it."])
+        assert "Tarrant Fnordwick" in terms
+        assert "Kosh" in terms
+        assert not any(t.startswith("Hey") for t in terms)
+        # A name and its own parts would spend tokens twice on one word.
+        assert "Tarrant" not in terms and "Fnordwick" not in terms
+
+    def test_identifiers_split_numbers_dropped(self):
+        terms = extract_terms(["", "see github.com/Hugo0/voiceio and v2 of x86_64 build 2026"])
+        assert "voiceio" in terms
+        assert not any(any(c.isdigit() for c in t) for t in terms)
+
+    def test_exclude_is_case_insensitive_and_dedupes_spellings(self):
+        terms = extract_terms(["", "Kalshi kalshi KALSHI Zorblax"], exclude=["zorblax"])
+        assert [t.lower() for t in terms] == ["kalshi"]
+
+    def test_vocabulary_long_tail_ranks_first(self):
+        terms = extract_terms(["", "Zorblax met Quuxley at Wibblecorp."],
+                              prefer=["Wibblecorp"])
+        assert terms[0] == "Wibblecorp"
+
+    def test_title_beats_selection_on_ties(self):
+        terms = extract_terms(["Quuxley", "Zorblax"])
+        assert terms == ["Quuxley", "Zorblax"]
+
+    def test_repeats_outrank_one_offs(self):
+        terms = extract_terms(["", "Zorblax once. Quuxley, Quuxley, Quuxley."])
+        assert terms[0] == "Quuxley"
+
+    def test_capped(self):
+        text = " ".join(f"Zorb{chr(97 + i)}lax" for i in range(20))
+        assert len(extract_terms(["", text], max_terms=5)) == 5
+
+    def test_huge_selection_is_cheap(self):
+        text = "the quick brown fox Zorblax jumps " * 20000
+        t0 = time.monotonic()
+        assert extract_terms(["", text]) == ["Zorblax"]
+        assert time.monotonic() - t0 < 1.0
+
+    def test_empty(self):
+        assert extract_terms(["", ""]) == []
+
+
+# ── budget share in the hotwords ──────────────────────────────────────────
+
+
+def _provider(terms: list[str]) -> BiasProvider:
+    from voiceio import config
+    from voiceio.vocabulary import VocabularyLoader
+    config.CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    (config.CONFIG_DIR / "vocabulary.txt").write_text("\n".join(terms) + "\n")
+    return BiasProvider(VocabularyLoader(config.ModelConfig()))
+
+
+def _vocab(n: int) -> list[str]:
+    # Distinct pronounceable made-up names, in file (= rank) order.
+    syll = ["ka", "zor", "bli", "mun", "tep", "vas", "quo", "rin", "lud", "fey"]
+    return [(syll[i % 10] + syll[(i // 10) % 10] + syll[(i * 7) % 10]).capitalize() + "x"
+            for i in range(n)]
+
+
+class TestBudget:
+    def test_no_screen_terms_is_unchanged(self):
+        bp = _provider(_vocab(60))
+        assert bp.bias_for(HOTWORDS).hotwords == bp.bias_for(HOTWORDS, []).hotwords
+
+    def test_screen_terms_displace_only_the_vocabulary_tail(self):
+        vocab = _vocab(60)
+        bp = _provider(vocab)
+        base = bp.bias_for(HOTWORDS).hotwords.split(", ")
+        merged = bp.bias_for(HOTWORDS, ["Quuxley", "Wibblecorp"]).hotwords.split(", ")
+        assert "Quuxley" in merged and "Wibblecorp" in merged
+        kept = [t for t in merged if t in vocab]
+        assert kept == base[:len(kept)], "the best-ranked terms survive, in order"
+        assert len(kept) < len(base)
+        assert count_tokens(", ".join(merged), "small") <= 120 + 2  # join slack
+
+    def test_screen_share_is_capped(self):
+        bp = _provider(_vocab(60))
+        many = [f"Zorb{chr(97 + i)}laxian" for i in range(20)]
+        merged = bp.bias_for(HOTWORDS, many).hotwords.split(", ")
+        screen = [t for t in merged if t in many]
+        assert 0 < len(screen) < len(many)
+        assert count_tokens(", ".join(screen), "small") <= SCREEN_TOKEN_SHARE
+        # The vocabulary keeps the rest of the budget.
+        assert len(merged) - len(screen) >= 10
+
+    def test_screen_terms_skip_what_hotwords_carry(self):
+        bp = _provider(["Kalshi", "HyperNEAT"])
+        assert bp.screen_terms(["Kalshi - Discord", "Quuxley and HyperNEAT"], HOTWORDS) == ["Quuxley"]
+
+    def test_unbounded_appends(self):
+        bp = _provider(_vocab(60))
+        caps = Capabilities(bias=BiasMode.UNBOUNDED)
+        merged = bp.bias_for(caps, ["Quuxley"]).hotwords.split(", ")
+        assert merged[-1] == "Quuxley" and len(merged) == 61
+
+    def test_decoder_without_hotwords_gets_nothing(self):
+        bp = _provider(["Kalshi"])
+        assert bp.screen_terms(["Quuxley"], Capabilities(bias=BiasMode.PROMPT)) == []
+
+    def test_extraction_failure_degrades_to_nothing(self):
+        bp = _provider(["Kalshi"])
+        with patch("voiceio.context_terms.extract_terms", side_effect=RuntimeError):
+            assert bp.screen_terms(["Quuxley"], HOTWORDS) == []
+
+
+# ── capture: deadline and degrade ─────────────────────────────────────────
+
+
+class TestCapture:
+    def test_slow_source_is_dropped_at_the_deadline(self):
+        gate = threading.Event()
+
+        def slow(_t):
+            gate.wait(5)
+            return "Zorblax"
+
+        t0 = time.monotonic()
+        ctx = capture(0.1, readers={"title": lambda _t: "Kalshi", "selection": slow})
+        elapsed = time.monotonic() - t0
+        gate.set()
+        assert elapsed < 0.5
+        assert ctx.title == "Kalshi" and ctx.selection == ""
+
+    def test_failing_source_degrades_silently(self):
+        def boom(_t):
+            raise OSError("no display")
+        ctx = capture(0.1, readers={"title": boom, "selection": lambda _t: "x"})
+        assert ctx == ScreenContext(title="", selection="x", secs=ctx.secs)
+
+    def test_no_tools_no_selection(self, monkeypatch):
+        monkeypatch.setattr(context_terms.shutil, "which", lambda _n: None)
+        assert context_terms._read_primary(0.1) == ""
+
+    def test_gnome_wayland_never_uses_wl_paste(self, monkeypatch):
+        """wl-paste can take focus on GNOME and drop the IBus preedit."""
+        from types import SimpleNamespace
+        monkeypatch.delenv("DISPLAY", raising=False)
+        monkeypatch.setattr("voiceio.platform.detect",
+                            lambda: SimpleNamespace(is_wayland=True, desktop="gnome"))
+        monkeypatch.setattr(context_terms.shutil, "which", lambda n: f"/usr/bin/{n}")
+        with patch.object(context_terms.subprocess, "run") as run:
+            assert context_terms._read_primary(0.1) == ""
+        run.assert_not_called()
+
+    def test_selection_read_has_the_deadline_as_timeout(self, monkeypatch):
+        monkeypatch.setenv("DISPLAY", ":0")
+        monkeypatch.setattr(context_terms.shutil, "which", lambda n: f"/usr/bin/{n}")
+        with patch.object(context_terms.subprocess, "run") as run:
+            run.return_value.returncode = 0
+            run.return_value.stdout = "Zorblax".encode()
+            assert context_terms._read_primary(0.15) == "Zorblax"
+        assert run.call_args.kwargs["timeout"] == 0.15
+        assert run.call_args.args[0][:2] == ["xclip", "-o"]
+
+
+# ── the daemon: never on the hotkey path ──────────────────────────────────
+
+
+@pytest.fixture
+def vio():
+    from test_app_wiring import _make_vio
+    from fakes import FakeDecoder
+    dec = FakeDecoder()
+    dec.transcribe.return_value = "hello"
+    v, _, _ = _make_vio(dec)
+    v.cfg.model.screen_vocabulary = True
+    yield v, dec
+    if v._session is not None:
+        v._session.cancel()
+
+
+class TestDaemon:
+    def test_capture_does_not_block_recording_start(self, vio):
+        v, dec = vio
+        gate = threading.Event()
+        captured = threading.Event()
+
+        def blocked_capture(*_a, **_k):
+            gate.wait(5)
+            captured.set()
+            return ScreenContext(title="Quuxley - Discord")
+
+        with patch("voiceio.context_terms.capture", side_effect=blocked_capture):
+            t0 = time.monotonic()
+            v.on_hotkey()
+            assert time.monotonic() - t0 < 1.0
+            assert v.recorder.is_recording, "recording started while capture blocks"
+            assert "Quuxley" not in (v._recording_bias.hotwords or "")
+            gate.set()
+            assert captured.wait(5)
+            for _ in range(100):
+                if "Quuxley" in (v._recording_bias.hotwords or ""):
+                    break
+                time.sleep(0.02)
+        assert "Quuxley" in (v._recording_bias.hotwords or "")
+        assert "Quuxley" in (v._session._bias.hotwords or ""), "applied to later passes"
+
+    def test_late_capture_never_touches_the_next_recording(self, vio):
+        v, _ = vio
+        gate = threading.Event()
+        with patch("voiceio.context_terms.capture",
+                   side_effect=lambda *a, **k: (gate.wait(5), ScreenContext(title="Quuxley"))[1]):
+            v.on_hotkey()
+            rid = v._recording
+            v._recording += 1   # as if this recording ended and another began
+            gate.set()
+            time.sleep(0.3)
+        v._recording = rid
+        assert "Quuxley" not in (v._recording_bias.hotwords or "")
+
+    def test_off_reads_nothing(self, vio):
+        v, _ = vio
+        v.cfg.model.screen_vocabulary = False
+        with patch("voiceio.context_terms.capture") as cap:
+            v.on_hotkey()
+            time.sleep(0.1)
+        cap.assert_not_called()

python_voiceio-1.9.0/tests/test_learn_language.py

@@ -0,0 +1,39 @@
+"""Fine-tuning and labeling follow the dictation language."""
+from __future__ import annotations
+
+import pytest
+
+from voiceio.cli import learn as learn_cli
+from voiceio.config import Config
+
+
+def _with_language(monkeypatch, lang):
+    cfg = Config()
+    cfg.model.language = lang
+    monkeypatch.setattr(learn_cli, "_cfg", lambda: cfg)
+
+
+def test_training_uses_the_dictation_language(monkeypatch):
+    """A Spanish voice trained under the "en" token learned the wrong prompt."""
+    _with_language(monkeypatch, "es")
+    assert learn_cli._train_language() == "es"
+
+
+def test_training_refuses_auto_with_a_hint(monkeypatch):
+    _with_language(monkeypatch, "auto")
+    with pytest.raises(SystemExit, match="model.language"):
+        learn_cli._train_language()
+
+
+def test_teacher_detects_when_language_is_auto(monkeypatch):
+    from voiceio.learn import teacher
+    monkeypatch.setattr("voiceio.core.decoders.faster_whisper.worker.load_model", lambda *a, **k: object())
+    assert teacher.WhisperTeacher("tiny", language="auto")._language is None
+    assert teacher.WhisperTeacher("tiny", language="es")._language == "es"
+
+
+def test_word_frequency_survives_auto_and_unknown_languages():
+    """language = "auto" raised LookupError in vocabulary biasing."""
+    from voiceio.wordfreq import is_common, is_known
+    assert is_common("house", "auto") and is_known("casa", "es")
+    assert not is_common("house", "xx")

{python_voiceio-1.8.2 → python_voiceio-1.9.0}/tests/test_postprocess.py

@@ -102,7 +102,20 @@ class TestCapitalization:
         assert cleanup("hello world") == "Hello world"
 
     def test_after_period(self):
-        assert cleanup("hello. world") == "Hello. World"
+        assert cleanup("hello? world") == "Hello? World"
+        assert cleanup("Hello. World") == "Hello. World"
+
+    def test_lowercase_after_a_segment_stop_is_a_comma(self):
+        # Whisper ends each segment with "." and continues the sentence in
+        # lowercase; capitalizing it made a false stop permanent.
+        assert cleanup("a bit bigger. and remove the latch.") == "A bit bigger, and remove the latch."
+        assert cleanup("hello. world") == "Hello, world"
+
+    def test_abbreviations_and_dotted_names_keep_their_dot(self):
+        assert cleanup("pears etc. and more") == "Pears etc. and more"
+        assert cleanup("use e.g. this one") == "Use e.g. this one"
+        assert cleanup("go to hugo0.com. and then") == "Go to hugo0.com. and then"
+        assert cleanup("I paused... and then") == "I paused... and then"
 
     def test_after_question_mark(self):
         assert cleanup("really? yes") == "Really? Yes"
@@ -184,7 +197,7 @@ class TestEdgeCases:
         assert result == "..."
 
     def test_unicode_accents(self):
-        assert cleanup("café. résumé") == "Café. Résumé"
+        assert cleanup("café? résumé") == "Café? Résumé"
 
 
 class TestWordMatchCompatibility:

python_voiceio-1.9.0/voiceio/__init__.py

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

{python_voiceio-1.8.2 → python_voiceio-1.9.0}/voiceio/app.py

@@ -168,6 +168,10 @@ class VoiceIO:
         threading.Thread(
             target=retention.prune, args=(cfg.data,), daemon=True,
         ).start()
+        if cfg.model.screen_vocabulary:
+            # Word frequency tables load in ~1s; not on the first dictation.
+            from voiceio.context_terms import warm
+            threading.Thread(target=warm, args=(cfg.model.language,), daemon=True).start()
 
         # Hotkey deduplication
         self._hotkey_lock = threading.Lock()
@@ -557,10 +561,12 @@ class VoiceIO:
         # `voiceio vocab`/`corrections` apply from the next recording.
         bias = self.engine.bias()
         self._recording_bias = bias
-        if self.cfg.data.capture_context:
-            # Snapshot the dictation target now — focus may change by finalize
+        if self.cfg.data.capture_context or self.cfg.model.screen_vocabulary:
+            # Snapshot the dictation target now — focus may change by finalize.
+            # Off this thread: the chime and the mic never wait on it.
             self._context_title = None
-            threading.Thread(target=self._capture_context, daemon=True).start()
+            threading.Thread(target=self._capture_context, args=(self._recording,),
+                             daemon=True, name="screen-context").start()
         self._record_start = time.monotonic()
         self.recorder.start()
         self.recorder.set_on_auto_stop(self._on_auto_stop)
@@ -627,9 +633,29 @@ class VoiceIO:
             # No finalizer will run to release the input source, so do it here.
             self._typers.end(rid)
 
-    def _capture_context(self) -> None:
+    def _capture_context(self, rid: int) -> None:
         from voiceio import retention
-        self._context_title = retention.active_window_title()
+        if not self.cfg.model.screen_vocabulary:
+            self._context_title = retention.active_window_title()
+            return
+        from voiceio import context_terms
+        t0 = time.monotonic()
+        screen = context_terms.capture()
+        if self.cfg.data.capture_context:
+            self._context_title = screen.title or None
+        terms = self.engine.screen_terms([screen.title, screen.selection])
+        if not terms:
+            return
+        bias = self.engine.bias(screen_terms=terms)
+        with self._hotkey_lock:
+            if self._recording != rid or self._state != _State.RECORDING:
+                return
+            self._recording_bias = bias
+            if self._session is not None:
+                self._session.set_bias(bias)
+        # A count only: these are words from the user's screen.
+        log.debug("Screen vocabulary: %d term(s) from %s, ready %.0f ms after start",
+                  len(terms), "+".join(screen.sources()), (time.monotonic() - t0) * 1000)
 
     def _retention_extra(self, audio: np.ndarray | None) -> dict:
         """Save the utterance audio (before transcription, so it survives

{python_voiceio-1.8.2 → python_voiceio-1.9.0}/voiceio/cli/learn.py

@@ -417,6 +417,16 @@ def cmd_train(args: argparse.Namespace) -> None:
               f"  (compare with the current model, then `voiceio learn promote {run.name}`)")
 
 
+def _train_language() -> str:
+    """The language a fine-tune is trained under: the one dictation decodes
+    with. "auto" has no single answer, so it has to be set first."""
+    lang = _cfg().model.language or "en"
+    if lang == "auto":
+        raise SystemExit("Fine-tuning needs one language: set it with "
+                         "`voiceio config set model.language es` (your dictation language).")
+    return lang
+
+
 def _train(ds: Path, *, base: str = "small", epochs: int = 4, synthetic_share: float = 0.3,
            full: bool = False, remote: bool = False) -> Path | None:
     """Export `ds` and fine-tune on it; returns the run dir (None for --remote)."""
@@ -433,8 +443,11 @@ def _train(ds: Path, *, base: str = "small", epochs: int = 4, synthetic_share: f
         return None
     train.require_train_deps()
     hotwords = (folder / train.HOTWORDS_FILE).read_text(encoding="utf-8")
+    # The language token the model is trained under must be the one it decodes
+    # with: training a Spanish voice under "en" taught it the wrong prompt.
     hf = train.train(folder, run, train.TrainConfig(
-        base=base, epochs=epochs, decoder_only=False if full else None, hotwords=hotwords))
+        base=base, epochs=epochs, decoder_only=False if full else None, hotwords=hotwords,
+        language=_train_language()))
     train.convert(hf, run / "ct2")
     return run
 

{python_voiceio-1.8.2 → python_voiceio-1.9.0}/voiceio/config.py

@@ -90,6 +90,10 @@ class ModelConfig:
     # "modified_beam_search" (required for hotwords).
     decoding: str = ""
     vocabulary_file: str = ""  # path to vocabulary.txt
+    # Bias each dictation toward rare names on screen: the focused window's
+    # title and the selected text (voiceio/context_terms.py). Read locally
+    # when recording starts; never stored or sent anywhere.
+    screen_vocabulary: bool = True
     # Beam width of the passes whose text you keep (freezes and the final
     # tail); interim previews are always greedy. 1 is greedy: faster stop.
     beam_size: int = 5