python-voiceio 0.8.1__tar.gz → 0.8.3__tar.gz

{python_voiceio-0.8.1/python_voiceio.egg-info → python_voiceio-0.8.3}/PKG-INFO

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

{python_voiceio-0.8.1 → python_voiceio-0.8.3}/pyproject.toml

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

{python_voiceio-0.8.1 → python_voiceio-0.8.3/python_voiceio.egg-info}/PKG-INFO

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

{python_voiceio-0.8.1 → python_voiceio-0.8.3}/python_voiceio.egg-info/SOURCES.txt

@@ -42,6 +42,7 @@ tests/test_robustness.py
 tests/test_security_hardening.py
 tests/test_snapshots.py
 tests/test_streaming.py
+tests/test_tokens.py
 tests/test_transcriber.py
 tests/test_tts.py
 tests/test_vad.py
@@ -79,8 +80,10 @@ voiceio/retention.py
 voiceio/service.py
 voiceio/snapshots.py
 voiceio/streaming.py
+voiceio/tokens.py
 voiceio/transcriber.py
 voiceio/vad.py
+voiceio/vocab_stats.py
 voiceio/vocabulary.py
 voiceio/wizard.py
 voiceio/wordfreq.py

{python_voiceio-0.8.1 → python_voiceio-0.8.3}/tests/test_audio_quality.py

@@ -125,10 +125,31 @@ class TestPromptBudget:
     output. Oversized bias inputs truncated real transcriptions mid-utterance
     (2026-07-05 regression). These bounds must hold."""
 
-    def test_hotwords_capped(self):
-        from unittest.mock import MagicMock, patch
-        from voiceio.app import _HOTWORDS_MAX_CHARS
-        assert _HOTWORDS_MAX_CHARS <= 700
+    def test_hotwords_budget_leaves_room_to_transcribe(self):
+        """The bound that actually matters, in the unit that actually matters.
+
+        The old assertion was `_HOTWORDS_MAX_CHARS <= 700` — but chars are the
+        wrong unit: proper nouns tokenize at ~2.6 chars/token, so 600 chars was
+        really 238 tokens, already past faster-whisper's 223 cap.
+        """
+        from voiceio.app import _HOTWORDS_TOKEN_BUDGET
+        from voiceio.tokens import (
+            HOTWORDS_TOKEN_CAP,
+            MAX_SEQUENCE_TOKENS,
+            OUTPUT_RESERVE_TOKENS,
+            PROMPT_TOKEN_BUDGET,
+        )
+
+        # Past this, faster-whisper silently discards the tail of the list.
+        assert _HOTWORDS_TOKEN_BUDGET <= HOTWORDS_TOKEN_CAP
+        # The invariant that actually protects the user: hotwords + prompt must
+        # leave enough to transcribe with. Violating it truncated freeze chunks
+        # mid-sentence (~37 words of room for a 45-60 word chunk) and, worst
+        # case, drove the decode budget to <=0 (ValueError).
+        overhead = 4  # sot_prev + sot_sequence
+        left = (MAX_SEQUENCE_TOKENS - _HOTWORDS_TOKEN_BUDGET
+                - PROMPT_TOKEN_BUDGET - overhead)
+        assert left >= OUTPUT_RESERVE_TOKENS
 
     def test_prompt_builder_default_budget_small(self):
         from voiceio.prompt import PromptBuilder

{python_voiceio-0.8.1 → python_voiceio-0.8.3}/tests/test_ibus_ping.py

@@ -4,10 +4,16 @@ socket path silently starves the healthy instance)."""
 from __future__ import annotations
 
 import socket
+import sys
 import threading
 
+import pytest
+
 import voiceio.ibus as ibus_mod
 
+# IBus (and AF_UNIX DGRAM + Linux abstract autobind) is Linux-only.
+pytestmark = pytest.mark.skipif(sys.platform != "linux", reason="IBus is Linux-only")
+
 
 def test_no_socket_returns_false(tmp_path, monkeypatch):
     monkeypatch.setattr(ibus_mod, "SOCKET_PATH", tmp_path / "nope.sock")

python_voiceio-0.8.3/tests/test_tokens.py

@@ -0,0 +1,107 @@
+"""Tests for exact Whisper token counting and the shared 448-token budget.
+
+Every budget here used to be a character count with a guessed chars/token ratio.
+The guess was wrong in the direction that mattered: proper nouns tokenize at
+~2.6 chars/token vs prose's ~4.0, so the old 600-char hotwords cap was really
+238 tokens — past faster-whisper's 223 cap, which then silently dropped terms
+and starved the output budget.
+"""
+from __future__ import annotations
+
+from unittest.mock import patch
+
+import pytest
+
+from voiceio.tokens import (
+    HOTWORDS_TOKEN_CAP,
+    MAX_SEQUENCE_TOKENS,
+    OUTPUT_RESERVE_TOKENS,
+    PROMPT_TOKEN_BUDGET,
+    _tokenizer,
+    count_tokens,
+    truncate_to_tokens,
+)
+
+# Most tests here are self-consistent — they count and assert with the same
+# function, so the estimate fallback is fine. A few assert properties of the
+# REAL tokenizer and are meaningless against a fixed chars/token constant; those
+# need a cached model, which CI runners don't have.
+needs_tokenizer = pytest.mark.skipif(
+    _tokenizer("small") is None,
+    reason="no cached whisper tokenizer (CI runners have no model cache)",
+)
+
+
+class TestCountTokens:
+    def test_empty(self):
+        assert count_tokens("", "small") == 0
+
+    def test_counts_real_tokens(self):
+        n = count_tokens("Grafana, Hetzner, OpenRouter", "small")
+        assert 5 < n < 30
+
+    @needs_tokenizer
+    def test_proper_nouns_cost_more_than_prose_per_char(self):
+        """The measured fact the whole redesign rests on.
+
+        Only meaningful against the real tokenizer: the fallback is a fixed
+        chars/token constant, which makes both ratios equal by construction.
+        """
+        nouns = "Kalshi, Metaculus, HyperNEAT, Kubernetes, Hetzner, Grafana"
+        prose = "the quick brown fox jumps over the lazy dog and then it runs"
+        nouns_ratio = len(nouns) / count_tokens(nouns, "small")
+        prose_ratio = len(prose) / count_tokens(prose, "small")
+        assert nouns_ratio < prose_ratio
+
+    def test_falls_back_to_estimate_without_tokenizer(self):
+        """No tokenizer must degrade to an estimate, never break dictation."""
+        import voiceio.tokens as t
+        with patch.dict(t._cache, {"bogus-model": None}, clear=False):
+            n = count_tokens("hello world", "bogus-model")
+        assert n > 0
+
+    def test_survives_a_broken_tokenizer(self):
+        import voiceio.tokens as t
+
+        class _Boom:
+            def encode(self, _):
+                raise RuntimeError("corrupt")
+
+        with patch.dict(t._cache, {"broken": _Boom()}, clear=False):
+            assert count_tokens("hello world", "broken") > 0
+
+
+class TestTruncateToTokens:
+    def test_noop_when_within_budget(self):
+        assert truncate_to_tokens("short text", 100, "small") == "short text"
+
+    def test_trims_to_budget(self):
+        text = "word " * 500
+        out = truncate_to_tokens(text, 50, "small")
+        assert count_tokens(out, "small") <= 50
+        assert out  # not emptied
+
+    def test_keeps_the_end(self):
+        """Prompts condition the audio that follows, so the OLDEST context goes."""
+        text = "alpha beta gamma delta " * 50 + "FINALWORD"
+        out = truncate_to_tokens(text, 20, "small")
+        assert "FINALWORD" in out
+
+    def test_zero_budget_is_empty(self):
+        assert truncate_to_tokens("anything", 0, "small") == ""
+
+
+class TestSharedBudget:
+    def test_budgets_leave_room_to_transcribe(self):
+        """hotwords + prompt + output must fit 448, with output usable.
+
+        Before this, the live config spent 223 (hotwords) + 171 (prompt) and
+        left ~50 tokens — about 37 words — to transcribe a freeze chunk holding
+        45-60. Worst case it went negative and faster-whisper raised
+        "The maximum decoding length must be > 0".
+        """
+        from voiceio.app import _HOTWORDS_TOKEN_BUDGET
+
+        total = _HOTWORDS_TOKEN_BUDGET + PROMPT_TOKEN_BUDGET + OUTPUT_RESERVE_TOKENS
+        assert total + 4 <= MAX_SEQUENCE_TOKENS
+        assert _HOTWORDS_TOKEN_BUDGET <= HOTWORDS_TOKEN_CAP

{python_voiceio-0.8.1 → python_voiceio-0.8.3}/tests/test_transcriber.py

@@ -166,3 +166,103 @@ class TestTimeoutRaises:
             with pytest.raises(TranscriptionError):
                 t.transcribe(np.zeros(16000, dtype=np.float32))
         assert t.last_segments == []
+
+
+class TestWorkerStartTimeout:
+    """A worker that never reports READY must not wedge the daemon.
+
+    faster-whisper's model load contacts huggingface_hub even for a cached
+    model; on a blackholed route that connect hangs indefinitely. An unbounded
+    READY handshake then holds the transcribe lock forever and every later
+    dictation silently returns "".
+    """
+
+    def test_start_raises_instead_of_hanging(self):
+        import threading
+        from voiceio.transcriber import Transcriber, TranscriptionError
+
+        mock_proc = MagicMock()
+        mock_proc.poll.return_value = None
+        mock_proc.stdout.readline.side_effect = lambda: threading.Event().wait()
+
+        with patch("voiceio.transcriber.subprocess.Popen", return_value=mock_proc), \
+             patch("voiceio.transcriber.WORKER_START_TIMEOUT", 0.1):
+            with pytest.raises(TranscriptionError, match="failed to start"):
+                Transcriber(ModelConfig())
+
+        # The hung process is reaped, not leaked.
+        assert mock_proc.terminate.called or mock_proc.kill.called
+
+    def test_start_raises_on_garbage_handshake(self):
+        from voiceio.transcriber import Transcriber, TranscriptionError
+
+        mock_proc = MagicMock()
+        mock_proc.poll.return_value = None
+        mock_proc.stdout.readline.return_value = "Traceback: boom\n"
+
+        with patch("voiceio.transcriber.subprocess.Popen", return_value=mock_proc):
+            with pytest.raises(TranscriptionError, match="failed to start"):
+                Transcriber(ModelConfig())
+
+
+class TestDecodeTimeoutIsLazy:
+    """The timed-out call fails regardless, so reloading the model inline would
+    hold the lock through a multi-second start and starve the final pass."""
+
+    def test_decode_timeout_does_not_reload_inline(self):
+        import numpy as np
+        from voiceio.transcriber import Transcriber, TranscriptionError
+
+        mock_proc = MagicMock()
+        mock_proc.stdout.readline.return_value = "READY\n"
+        mock_proc.poll.return_value = None
+        with patch("voiceio.transcriber.subprocess.Popen", return_value=mock_proc):
+            t = Transcriber(ModelConfig())
+
+        with patch.object(t, "_read_with_timeout", return_value=None), \
+             patch.object(t, "_kill_worker") as kill, \
+             patch.object(t, "_ensure_worker") as ensure:
+            with pytest.raises(TranscriptionError):
+                t.transcribe(np.zeros(16000, dtype=np.float32))
+
+        assert kill.called
+        # Only the entry call — never a second, restarting one.
+        assert ensure.call_count == 1
+
+
+class TestWorkerModelLoad:
+    """A cached model must load without touching the network."""
+
+    def test_prefers_local_cache(self):
+        from voiceio import worker
+
+        with patch("voiceio.worker.WhisperModel") as wm:
+            worker.load_model("small", device="auto", compute_type="int8")
+        assert wm.call_args.kwargs["local_files_only"] is True
+
+    def test_falls_back_to_network_when_not_cached(self):
+        from voiceio import worker
+
+        sentinel = object()
+        with patch("voiceio.worker.WhisperModel",
+                   side_effect=[OSError("not cached"), sentinel]) as wm:
+            got = worker.load_model("small")
+        assert got is sentinel
+        assert "local_files_only" not in wm.call_args.kwargs
+
+    def test_every_whisper_load_goes_through_the_guarded_helper(self):
+        """A raw WhisperModel(...) anywhere else reintroduces the hang: the
+        teacher audit and the wizard both load models on this same box."""
+        import re
+        from pathlib import Path
+
+        src = Path(__file__).resolve().parent.parent / "voiceio"
+        offenders = []
+        for py in src.rglob("*.py"):
+            for i, line in enumerate(py.read_text().splitlines(), 1):
+                if re.search(r"(?<!def )\bWhisperModel\(", line):
+                    # worker.load_model is the one sanctioned construction site.
+                    if py.name == "worker.py":
+                        continue
+                    offenders.append(f"{py.relative_to(src)}:{i}")
+        assert not offenders, f"unguarded WhisperModel loads: {offenders}"

{python_voiceio-0.8.1 → python_voiceio-0.8.3}/tests/test_vocabulary.py

@@ -1,7 +1,8 @@
-"""Tests for vocabulary file loading."""
+"""Tests for vocabulary file loading, ranking and token-budgeted selection."""
 from __future__ import annotations
 
 import os
+import time
 
 from voiceio.config import ModelConfig
 from voiceio.vocabulary import VocabularyLoader, add_terms, load_vocabulary
@@ -41,14 +42,21 @@ class TestLoadVocabulary:
         result = load_vocabulary(cfg)
         assert result == ""
 
-    def test_truncation(self, tmp_path):
+    def test_load_is_untruncated(self, tmp_path):
+        """load_vocabulary returns EVERY term — truncating here was the bug.
+
+        Budgeting moved to select_terms (token-aware, ranked). The callers that
+        need the whole list — postcorrect's LLM, and the mining gate's "is this
+        already in your vocabulary?" check — were silently reading a truncated
+        view before.
+        """
         vocab_file = tmp_path / "vocabulary.txt"
-        # Create a very long vocabulary list
         terms = [f"LongTechnicalTerm{i:04d}" for i in range(100)]
         vocab_file.write_text("\n".join(terms))
         cfg = ModelConfig(vocabulary_file=str(vocab_file))
         result = load_vocabulary(cfg)
-        assert len(result) <= 800
+        assert len(result) > 800
+        assert result.count(",") == 99
 
     def test_no_config_uses_default_location(self, tmp_path, monkeypatch):
         """With empty vocabulary_file, checks CONFIG_DIR/vocabulary.txt."""
@@ -145,13 +153,15 @@ class TestVocabularyLoader:
 
         import voiceio.vocabulary as vocab_mod
         calls = {"n": 0}
-        orig = vocab_mod.load_vocabulary
+        orig = vocab_mod.load_terms
 
         def _counting(model_cfg):
             calls["n"] += 1
             return orig(model_cfg)
 
-        monkeypatch.setattr(vocab_mod, "load_vocabulary", _counting)
+        # load_terms is the real read now; patching load_vocabulary would pass
+        # vacuously since the loader no longer calls it.
+        monkeypatch.setattr(vocab_mod, "load_terms", _counting)
         loader.get()
         loader.get()
         assert calls["n"] == 0  # mtime unchanged → no reload
@@ -160,3 +170,89 @@ class TestVocabularyLoader:
         cfg = ModelConfig(vocabulary_file=str(tmp_path / "nope.txt"))
         loader = VocabularyLoader(cfg)
         assert loader.get() == ""
+
+
+class TestSelectTerms:
+    """Selection is permanent: the hotword budget holds ~40-60 terms and the
+    vocabulary only grows, so who gets a slot is the whole game."""
+
+    def _stats(self, tmp_path, data):
+        from voiceio.vocab_stats import VocabStats
+        s = VocabStats(tmp_path / "vocab_stats.json")
+        s._stats = {k.lower(): v for k, v in data.items()}
+        return s
+
+    def test_respects_token_budget(self):
+        from voiceio.vocabulary import select_terms
+        from voiceio.tokens import count_tokens
+
+        terms = [f"LongTechnicalTerm{i:04d}" for i in range(100)]
+        got = select_terms(terms, token_budget=50, model_name="small")
+        assert got  # something fits
+        assert len(got) < len(terms)  # but not everything
+        assert count_tokens(", ".join(got), "small") <= 50
+
+    def test_actually_fills_the_budget(self):
+        """Guards the mistake this replaced: costing terms one at a time and
+        summing double-counts the ", " joins, so the budget was only ~half
+        spent (19 terms / 64 of 120 tokens on the real vocabulary)."""
+        from voiceio.vocabulary import select_terms
+        from voiceio.tokens import count_tokens
+
+        terms = [f"Term{i:04d}" for i in range(200)]
+        budget = 100
+        got = select_terms(terms, token_budget=budget, model_name="small")
+        used = count_tokens(", ".join(got), "small")
+        assert used <= budget
+        # Within one term's cost of the budget — no silent under-fill.
+        assert used >= budget - 8
+        # And adding the next-ranked term must genuinely overflow.
+        nxt = [t for t in terms if t not in got][0]
+        assert count_tokens(", ".join(got + [nxt]), "small") > budget
+
+    def test_never_emits_a_partial_term(self):
+        """The old code did vocab[:600] — a raw char slice that could cut a term
+        in half and feed the decoder a fragment."""
+        from voiceio.vocabulary import select_terms
+
+        terms = ["Kubernetes", "Grafana", "Hetzner", "OpenRouter", "Metaculus"]
+        got = select_terms(terms, token_budget=12, model_name="small")
+        assert all(t in terms for t in got)
+
+    def test_ranks_by_usage(self, tmp_path):
+        from voiceio.vocabulary import select_terms
+
+        terms = ["Alpha", "Beta", "Gamma"]
+        stats = self._stats(tmp_path, {
+            "Gamma": {"hits": 50, "last_seen_ts": time.time()},
+        })
+        # Budget for roughly one term: the used one must win despite file order.
+        got = select_terms(terms, token_budget=6, model_name="small", stats=stats)
+        assert got[0] == "Gamma"
+
+    def test_recency_beats_stale_volume(self, tmp_path):
+        """A term used heavily months ago should lose to one used today."""
+        from voiceio.vocabulary import select_terms
+
+        now = time.time()
+        stats = self._stats(tmp_path, {
+            "Stale": {"hits": 100, "last_seen_ts": now - 365 * 86400},
+            "Fresh": {"hits": 5, "last_seen_ts": now},
+        })
+        got = select_terms(["Stale", "Fresh"], token_budget=6,
+                           model_name="small", stats=stats, now=now)
+        assert got[0] == "Fresh"
+
+    def test_cold_start_is_file_order(self):
+        """No stats → degrade to exactly the previous behaviour, never worse."""
+        from voiceio.vocabulary import select_terms
+
+        terms = ["First", "Second", "Third"]
+        got = select_terms(terms, token_budget=1000, model_name="small", stats=None)
+        assert got == terms
+
+    def test_empty_and_zero_budget(self):
+        from voiceio.vocabulary import select_terms
+
+        assert select_terms([], token_budget=100, model_name="small") == []
+        assert select_terms(["A"], token_budget=0, model_name="small") == []

python_voiceio-0.8.3/voiceio/__init__.py

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

{python_voiceio-0.8.1 → python_voiceio-0.8.3}/voiceio/app.py

@@ -97,10 +97,20 @@ def _import_graphical_env() -> None:
 _HEALTH_CHECK_INTERVAL = 10  # seconds between health checks
 
 # Whisper's decoder has a hard 448-token sequence budget shared by hotwords,
-# initial_prompt AND the transcription output. Hotwords + prompt must stay
-# well under half of it or output gets truncated mid-utterance.
-# ~600 chars ≈ 150 tokens.
-_HOTWORDS_MAX_CHARS = 600
+# initial_prompt AND the transcription output. Hotwords + prompt must stay well
+# under half of it or output gets truncated mid-utterance.
+#
+# This is a TOKEN budget, counted for real (voiceio.tokens) — the old 600-char
+# proxy assumed ~4 chars/token, but proper nouns (the whole point of a custom
+# vocabulary) run ~2.6, so "600 chars" was really 238 tokens: already past
+# faster-whisper's own 223-token hotwords cap, which then silently dropped the
+# tail.
+#
+# Derived, not guessed: 448 total - 200 output reserve - 120 prompt - 4 overhead
+# = 124. At ~3.5 tokens/term that is ~34 terms. Fewer terms than the old config
+# pretended to carry, but they are real: the old 223-token list left ~50 tokens
+# to transcribe with and truncated freeze chunks mid-sentence.
+_HOTWORDS_TOKEN_BUDGET = 120
 
 
 class _State(enum.Enum):
@@ -309,30 +319,56 @@ class VoiceIO:
             self._do_start()
 
     def _refresh_hotwords(self) -> None:
-        """Rebuild Whisper hotwords from vocabulary + correction targets.
+        """Rebuild Whisper hotwords: rank by usage, fill the token budget.
 
-        The vocabulary read is mtime-cached (only a `stat` when unchanged), and
-        `set_hotwords` is called only when the merged string actually changed,
-        so this stays cheap enough to run on every recording start.
+        Selection is mandatory and permanent — the budget holds ~40-60 terms and
+        the vocabulary only grows — so the slots go to the terms actually being
+        dictated (voiceio.vocab_stats), highest-scoring first.
+
+        Both reads are mtime-cached and `set_hotwords` only fires when the string
+        changed, so the steady-state cost here is a couple of `stat` calls. That
+        matters: this runs synchronously before `recorder.start()`.
         """
-        vocab = self._vocab_loader.get()
+        terms = self._vocab_loader.get_selected(token_budget=_HOTWORDS_TOKEN_BUDGET)
         # Only merge RARE correction targets (proper nouns, technical terms):
         # common-word targets ("review", "company") add nothing to decoder bias
         # and hundreds of them blow Whisper's 448-token prompt+output budget,
         # which truncates transcriptions mid-utterance.
-        from voiceio.wordfreq import is_common
-        vocab_terms = [
-            t for t in self._corrections.vocabulary_terms()
-            if not is_common(t, self.cfg.model.language)
-        ]
-        if vocab_terms:
-            extra = ", ".join(vocab_terms)
-            vocab = f"{vocab}, {extra}" if vocab else extra
-        vocab = vocab[:_HOTWORDS_MAX_CHARS]
+        vocab = ", ".join(terms + self._rare_correction_targets())
         if vocab != self._hotwords:
             self._hotwords = vocab
-            if vocab:
-                self.transcriber.set_hotwords(vocab)
+            # Set unconditionally: an emptied vocabulary must CLEAR the hotwords,
+            # not leave the previous string biasing every future decode.
+            self.transcriber.set_hotwords(vocab or None)
+
+    def _record_vocab_usage(self, text: str) -> None:
+        """Record which vocabulary terms this utterance used (finalize path only).
+
+        This is the feedback signal that decides who gets the hotword budget next
+        time. Deliberately not on the recording-start path, and never fatal — a
+        usage counter must not be able to break a dictation.
+        """
+        try:
+            from voiceio import vocab_stats
+            vocab_stats.update_from_text(text, self._vocab_loader.get_all())
+        except Exception:  # noqa: BLE001
+            log.debug("vocab usage update failed", exc_info=True)
+
+    def _rare_correction_targets(self) -> list[str]:
+        """Correction targets worth biasing, cached against corrections mtime.
+
+        `is_common` over every target used to be recomputed on each recording
+        start; the result only changes when corrections.json does.
+        """
+        mtime = getattr(self._corrections, "_mtime", None)
+        if getattr(self, "_rare_targets_mtime", object()) != mtime:
+            from voiceio.wordfreq import is_common
+            self._rare_targets = [
+                t for t in self._corrections.vocabulary_terms()
+                if not is_common(t, self.cfg.model.language)
+            ]
+            self._rare_targets_mtime = mtime
+        return self._rare_targets
 
     def _do_start(self) -> None:
         """Transition to RECORDING."""
@@ -432,8 +468,13 @@ class VoiceIO:
         if self._postcorrect is not None:
             # Freshest context for the finalize pass: this recording's window
             # title (captured at start) and the latest transcripts/vocabulary.
+            #
+            # The FULL vocabulary, not the hotwords string: the decoder can only
+            # be biased with ~40-60 terms, but this is an LLM with no 448-token
+            # budget. The long tail that can never fit in hotwords gets its only
+            # chance to be corrected here.
             self._postcorrect.set_context(
-                vocabulary=self._hotwords,
+                vocabulary=", ".join(self._vocab_loader.get_all()),
                 recent=self._prompt_builder.recent(3),
                 title=self._context_title,
             )
@@ -552,6 +593,7 @@ class VoiceIO:
             self._play_feedback(final_text)
             stored = self._strip_voice_prefix(final_text)
             self._prompt_builder.add_transcript(stored)
+            self._record_vocab_usage(stored)
             latency = dict(session.final_latency)
             # stop-to-commit: what the user actually waits for
             latency["finalize_total"] = round(time.monotonic() - t_final, 3)

{python_voiceio-0.8.1 → python_voiceio-0.8.3}/voiceio/audit.py

@@ -169,9 +169,11 @@ def _read_metrics(path: Path | None = None) -> list[dict]:
 
 def _default_teacher():
     """Lazily build the offline teacher transcriber (distil-large-v3)."""
-    from faster_whisper import WhisperModel
+    from voiceio.worker import load_model
 
-    model = WhisperModel("distil-large-v3", device="cpu", compute_type="int8")
+    # Cache-first: the module docstring's "nothing here uses the network" only
+    # holds if the load itself can't reach out and hang (see load_model).
+    model = load_model("distil-large-v3")
 
     def _transcribe(wav_path: Path) -> str:
         segments, _ = model.transcribe(
@@ -323,14 +325,42 @@ def run_audit(
     return report
 
 
+def _last_seen_map(terms: list[str]) -> dict[str, float]:
+    """When each term was last dictated.
+
+    Prefers vocab_stats.json, which the runtime maintains per utterance. Falls
+    back to scanning history only when no stats exist yet (fresh install, or a
+    daemon that hasn't finalized a dictation since stats landed) — that scan is
+    O(entries x terms) over the whole history, which at 6k entries and 300+
+    terms is not worth running when the answer is already recorded.
+    """
+    from voiceio.vocab_stats import VocabStats
+
+    stats = VocabStats()
+    stats.load()
+    if stats.as_dict():
+        return {t: float(stats.get(t).get("last_seen_ts", 0.0) or 0.0) for t in terms}
+
+    from voiceio import history
+
+    last_seen: dict[str, float] = {}
+    for e in history.read(limit=0):
+        text = (e.get("text") or "").lower()
+        ts = e.get("ts", 0.0)
+        for term in terms:
+            if term.lower() in text and ts > last_seen.get(term, 0.0):
+                last_seen[term] = ts
+    return last_seen
+
+
 def _audit_vocabulary(cfg, teacher_texts, now, report) -> None:
     """Confirm vocab terms the teacher heard; age out terms unseen for 90 days.
 
-    Aging moves a term to the bottom of vocabulary.txt rather than deleting it:
-    the 800-char loader truncates the tail, so stale terms fall out of the
-    hotword budget but can rejoin if used again.
+    Aging moves a term to the bottom of vocabulary.txt rather than deleting it.
+    File order is now only the tie-break for terms with no usage signal —
+    vocabulary.select_terms ranks by vocab_stats first — but keeping stale terms
+    at the bottom still means they lose ties, and they rejoin on next use.
     """
-    from voiceio import history
     from voiceio.vocabulary import _read_terms, resolve_vocab_path
 
     path = resolve_vocab_path(cfg.model)
@@ -341,16 +371,7 @@ def _audit_vocabulary(cfg, teacher_texts, now, report) -> None:
         return
 
     teacher_blob = "\n".join(teacher_texts)
-    # Last time each term appeared in a live transcript.
-    entries = history.read(limit=0)
-    last_seen: dict[str, float] = {}
-    for e in entries:
-        text = e.get("text", "")
-        ts = e.get("ts", 0.0)
-        low = text.lower()
-        for term in terms:
-            if term.lower() in low and ts > last_seen.get(term, 0.0):
-                last_seen[term] = ts
+    last_seen = _last_seen_map(terms)
 
     fresh: list[str] = []
     aged: list[str] = []