python-voiceio 0.8.2__py3-none-any.whl → 0.9.0__py3-none-any.whl

{python_voiceio-0.8.2.dist-info → python_voiceio-0.9.0.dist-info}/METADATA

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

{python_voiceio-0.8.2.dist-info → python_voiceio-0.9.0.dist-info}/RECORD

@@ -1,18 +1,19 @@
-python_voiceio-0.8.2.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
-voiceio/__init__.py,sha256=B7GiO0rd49YwtLYjvPg4lmCZEDlMTonslQKdSImaMJk,22
+python_voiceio-0.9.0.dist-info/licenses/LICENSE,sha256=Gz61o8jFTAvZUZyB3nWDB3DQQVuipjfPkVu9W8hBHM0,1072
+voiceio/__init__.py,sha256=H9NWRZb7NbeRRPLP_V1fARmLNXranorVM-OOY-8_2ug,22
 voiceio/__main__.py,sha256=xT5QCGGreYMisHO7Lh_Y-xAQ2TOzG2D7npKknGNcWSY,53
-voiceio/app.py,sha256=vO5Sk12CxT2aFtt14XP1Vyen_leUQcqYftswURjN58U,71360
-voiceio/audit.py,sha256=vX3x-YAhmt6EZYRZd0_6wvTquZu5sxGMvH45BhSBnCk,14915
+voiceio/app.py,sha256=ScrUVDQQ_YbAFKKSMOhaRPX_WTcPuenhnRdSzWMxThE,73785
+voiceio/audit.py,sha256=p4F2BBX4wEC9eS8MSplzfXL52XC2dyIKbgrRvR-WbTU,15802
 voiceio/autocorrect.py,sha256=jGsglEYwAHWk2uWedeEZzyAMW2LWO_8nQGZgrWYy4Dc,26552
 voiceio/autocorrect_state.py,sha256=BNzdHP5slcOV_-OU4MlaKE7xgVJzrPncsYFK30JWTs8,6858
 voiceio/backends.py,sha256=-rs1YhPblub4NjFb6qCD7Ih9FqBRXtPuvjVv9bQoQ1w,368
-voiceio/cli.py,sha256=_HfcWQt2Jf34YfI4W1RavsyqegQy9jrg0nwLe6DvD6E,71639
+voiceio/cli.py,sha256=QE8N7N3d1O7r9-u_jbYMAH9gw0ILX7dSxDZZYj83lIs,78969
 voiceio/clipboard_read.py,sha256=lz75CkRGh7pyvO6xvoUmxJDl-Gwie1xlXQHK70PO84I,4261
 voiceio/commands.py,sha256=Vhtn8s5G5OcCbRN44YZ-_14Fa85ISXl_3Ix-KqSHs2A,4694
-voiceio/config.py,sha256=kpKileJk5mAp4eB7tXBblzOxmlxIfMvRDzY2tjwTkSQ,14465
+voiceio/config.py,sha256=DA1PGIanhrPjWkVT6jj0NSFslW9vuegzV6eMJNuKBzM,15273
 voiceio/consent.py,sha256=jtdp1TkTbicUSTCDmV4qo4SdbS4kQpYzy1Kjc_7pJVw,1883
 voiceio/corrections.py,sha256=7moKhkVvo5CZU1mZobV2-MajkcHiwliKBY1dSBFh0w0,7445
 voiceio/demo.py,sha256=QRNJuNObXCsjwGD-Cz3dh81cfb21xiuSeVyyU720U9Q,8673
+voiceio/evaluate.py,sha256=_4AZRBsa9fqIiYY1CASmzliy6-RmIjyEjiduFpINXRs,12019
 voiceio/feedback.py,sha256=TyUy_wy5HNTO0u3opx58aaPXz7mAqeN98UbNdLfnoiw,5136
 voiceio/health.py,sha256=5YNu1mMzwTo6I_Z_Mu3Bs46ZHDpVmxP0AXyMNAbaczc,15707
 voiceio/hints.py,sha256=dmoiMAJ0YGTWwFc9kIPvEs_BQJN7UEUiwYuLUD_GoQQ,1415
@@ -30,12 +31,14 @@ voiceio/retention.py,sha256=i_VWPCyykT4kQ1uKilTplpiIrACTYljn09BU1vL71A0,6019
 voiceio/service.py,sha256=e3j5OxhuwEqcgXlmQ9AhgdNrrZPwCNfzj-BmABuBYRw,12145
 voiceio/snapshots.py,sha256=bm-lzIeYucDUDlPBZiFiWd-jyB2I6Ft1jRANZCO6go4,2351
 voiceio/streaming.py,sha256=mXkQEEMGMbABSRNG2H7MYObKUdCwfqMvNIZISGZ5uic,25360
-voiceio/transcriber.py,sha256=NWYMZpIhYccUBKzcFyMzjH1MTMNv4bG9op5Qw5reOhI,11608
+voiceio/tokens.py,sha256=BbOXnsDIfWYMVbSp25PYG1UtK7-7OtZ7q7l4kOIm9OY,5292
+voiceio/transcriber.py,sha256=12o3POqS8nqJdXXQH-riZlSVChZPP_UP1bNLd7qNfTs,12303
 voiceio/vad.py,sha256=72_ICk4jSuSPYvTHdHYtHzY8W5uaGEOz5FTdqkolJi8,5327
-voiceio/vocabulary.py,sha256=eGV7QZs3tN6Cw5YpyoZsVEk2M5fJvie1n2XFi9CD4hw,6321
-voiceio/wizard.py,sha256=AwjwrocrQp0DPSOMZ0m6z6G3hlo9VPceEwPzR9-xXe0,80227
+voiceio/vocab_stats.py,sha256=obz_mdUqlSoAD15wkIQM-1X3AXNum74VKDX_bu1mEZw,5403
+voiceio/vocabulary.py,sha256=_7LjCS5Mqqh7PLKl8LMPIPsIlyfNKTaaLlfJ2BDfwtM,11355
+voiceio/wizard.py,sha256=1zIYGixPsyu2OhNBnxk-DiErUgmVUvxhWvGoauiQXFY,80349
 voiceio/wordfreq.py,sha256=2UMjW1xIFqo5EchXzsXPizUhRb9N18CVgjnXso1wsgw,2382
-voiceio/worker.py,sha256=Ec_OChl6CCX1XHdNYdmx_4l4_sIRexyxih64-PBNhjs,3233
+voiceio/worker.py,sha256=AkEYu2OzAup00ew24DYO7SfA91xTBnFvbtioGE0nsK4,3520
 voiceio/hotkeys/__init__.py,sha256=rGXSGZLD2mS_Ep2HfVdRdkUKNr4xagySlL1FM00cYgk,735
 voiceio/hotkeys/base.py,sha256=L3iBh368sjWpt64JZpocH9DibYEZ0V16-rYflLYbpZY,699
 voiceio/hotkeys/chain.py,sha256=8pvPhipmxWwmGG9DRXy8dlEKTPFILxNzYO-adcvw5Ps,2800
@@ -65,14 +68,14 @@ voiceio/tts/player.py,sha256=tyKeJzDHKCpIzlPzQGTWIuDHQJT4DDGbFD0hK11knuY,1698
 voiceio/typers/__init__.py,sha256=lFIMEjfPGw8tfYGELhsq0mYM849uKLx_SZhbHqGJrlo,1071
 voiceio/typers/base.py,sha256=VVMgARlpaSVqen-zFUssnbUMYDrWryacRE8MKvlLk-s,1180
 voiceio/typers/chain.py,sha256=F4QcAMTzYvrxeC-_Er4CbjnqQ1ONYjt7Fp11y8PNpqU,2964
-voiceio/typers/clipboard.py,sha256=cxeOL_a_P2HeJ-nr-klG94nHjbd9rWu3nxGDXmyfzys,6110
-voiceio/typers/ibus.py,sha256=ciaB5OgW5RqgLVdGZqoBhU4q1ttkh7o2H4aAoXSCqbA,18531
+voiceio/typers/clipboard.py,sha256=8MJp3fEWCe3bvagqwevd3SgVVD830--AfEY0k87dkW0,7432
+voiceio/typers/ibus.py,sha256=q2zXdjn68YUGSdHRvnflAhPN4-mE4Op2zKlOx_4FXYQ,20080
 voiceio/typers/pynput_type.py,sha256=DTtkT59M-EKOAlTNkvcZrRvf_Fq52OpI8S5t_8S-QAY,1887
 voiceio/typers/wtype.py,sha256=d1wG-HZdYDQxXIysV_Xvk9HixDpaJgl3VEoKbP5vhIs,1786
 voiceio/typers/xdotool.py,sha256=dh1zhPqUT8ihJahJ7ZKm6PtfYY087UAzADx664DvQOM,1356
 voiceio/typers/ydotool.py,sha256=dt0W9ot__W8LQG2so8vZLGIw9leK2Q6g3i-Voo0LXE4,5327
-python_voiceio-0.8.2.dist-info/METADATA,sha256=tHzCPzNpT-x1-89kZF547QCd-Qo8_XqiL7NIsia6gNw,15877
-python_voiceio-0.8.2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_voiceio-0.8.2.dist-info/entry_points.txt,sha256=U64fA65zxzyLoC8bgbn2ztQVWHLsc0o0H0qCk1J9DMc,218
-python_voiceio-0.8.2.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
-python_voiceio-0.8.2.dist-info/RECORD,,
+python_voiceio-0.9.0.dist-info/METADATA,sha256=5Wkd2wpiUlDzxWnslJI6HdpHLRr1zWMdmZcbvb8CS1o,15877
+python_voiceio-0.9.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_voiceio-0.9.0.dist-info/entry_points.txt,sha256=U64fA65zxzyLoC8bgbn2ztQVWHLsc0o0H0qCk1J9DMc,218
+python_voiceio-0.9.0.dist-info/top_level.txt,sha256=piwtn309lD6uexQyXdZ-efAVBJF9y6Wfr48Z-8zkNhg,8
+python_voiceio-0.9.0.dist-info/RECORD,,

voiceio/__init__.py

@@ -1 +1 @@
-__version__ = "0.8.2"
+__version__ = "0.9.0"

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)

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] = []

voiceio/cli.py

@@ -83,6 +83,8 @@ def main() -> None:
     p_correct.add_argument("wrong", nargs="?", help="Misheard word/phrase")
     p_correct.add_argument("right", nargs="?", help="Correct replacement")
     p_correct.add_argument("--list", action="store_true", help="List all corrections")
+    p_correct.add_argument("--vocab", action="store_true",
+                           help="Show vocabulary and which terms fit the decoder budget")
     p_correct.add_argument("--remove", metavar="WORD", help="Remove a correction")
     p_correct.add_argument("--flagged", action="store_true",
                            help="Show words flagged by 'correct that'")
@@ -108,6 +110,14 @@ def main() -> None:
     p_history.add_argument("--path", action="store_true",
                            help="Print history file path")
 
+    # ── voiceio eval ───────────────────────────────────────────────────
+    p_eval = sub.add_parser(
+        "eval", help="Replay your retained audio across decoder configs and score them")
+    p_eval.add_argument("--max-audio-secs", type=float, default=900,
+                        help="Audio budget to replay (default: 900 = 15min)")
+    p_eval.add_argument("--json", action="store_true",
+                        help="Emit raw results as JSON")
+
     # ── voiceio demo ──────────────────────────────────────────────────
     sub.add_parser("demo", help="Interactive guided tour of voiceio features")
 
@@ -134,6 +144,8 @@ def main() -> None:
         _cmd_correct(args)
     elif args.command == "history":
         _cmd_history(args)
+    elif args.command == "eval":
+        _cmd_eval(args)
     elif args.command == "demo":
         _cmd_demo()
     elif args.command == "logs":
@@ -718,6 +730,138 @@ def _cmd_uninstall() -> None:
             print("\nvoiceio fully removed.")
 
 
+def _cmd_eval(args: argparse.Namespace) -> None:
+    """Score decoder configs against a teacher model on your own audio."""
+    import json as _json
+    import sys
+    import time
+
+    from voiceio.config import load
+    from voiceio.evaluate import default_matrix, evaluate
+    from voiceio.wizard import BOLD, DIM, GREEN, RESET, YELLOW
+
+    cfg = load()
+    matrix = default_matrix()
+
+    print(f"{BOLD}Evaluating {len(matrix)} decoder configs{RESET} "
+          f"{DIM}on up to {args.max_audio_secs:.0f}s of your retained audio{RESET}")
+    print(f"{DIM}Scored against a teacher model (distil-large-v3) — a proxy for")
+    print(f"ground truth, good for ranking configs, not for absolute accuracy.{RESET}\n")
+
+    last = [""]
+
+    def progress(name, i, n):
+        if name != last[0]:
+            last[0] = name
+            sys.stderr.write(f"\n  {name}: ")
+        sys.stderr.write(".")
+        sys.stderr.flush()
+
+    t0 = time.time()
+    scores = evaluate(cfg, matrix, max_audio_secs=args.max_audio_secs,
+                      on_progress=progress)
+    sys.stderr.write("\n\n")
+
+    if not scores:
+        print("No retained audio to evaluate. Dictate a few notes first "
+              "(audio is kept under [data] retain_audio).")
+        return
+
+    if args.json:
+        print(_json.dumps([{
+            "config": s.config.name, **s.config.as_dict(),
+            "clips": s.clips, "audio_secs": round(s.audio_secs, 1),
+            "wer": s.wer, "hallucinations": s.hallucinations,
+            "repetitions": s.repetitions, "empties": s.empties,
+            "crashes": s.crashes, "decode_secs": round(s.decode_secs, 1),
+        } for s in scores], indent=2))
+        return
+
+    best = scores[0]
+    shipped = next((s for s in scores if s.config.name == "shipped"), None)
+
+    print(f"  {'config':<24} {'WER':>7} {'halluc':>7} {'repeat':>7} "
+          f"{'empty':>6} {'crash':>6}")
+    print(f"  {'-'*24} {'-'*7} {'-'*7} {'-'*7} {'-'*6} {'-'*6}")
+    for s in scores:
+        mark = f" {GREEN}<- best{RESET}" if s is best else ""
+        if s is shipped and s is not best:
+            mark = f" {DIM}<- shipped{RESET}"
+        elif s is shipped:
+            mark = f" {GREEN}<- best (shipped){RESET}"
+        print(f"  {s.config.name:<24} {s.wer:>7.3f} {s.hallucinations:>7} "
+              f"{s.repetitions:>7} {s.empties:>6} {s.crashes:>6}{mark}")
+
+    print(f"\n  {DIM}{best.clips} clips, {best.audio_secs:.0f}s audio, "
+          f"{time.time()-t0:.0f}s total{RESET}")
+
+    if shipped and best is not shipped:
+        delta = (shipped.wer - best.wer) / shipped.wer * 100 if shipped.wer else 0
+        print(f"\n  {YELLOW}'{best.config.name}' beats the shipped config by "
+              f"{delta:.0f}% WER.{RESET}")
+        # A WER win means nothing if it comes from the failure mode the knob
+        # exists to prevent, so make that trade explicit rather than implied.
+        if best.hallucinations > shipped.hallucinations:
+            print(f"  {YELLOW}But it hallucinates more "
+                  f"({best.hallucinations} vs {shipped.hallucinations}) — "
+                  f"that's what vad_filter is for.{RESET}")
+        if best.repetitions > shipped.repetitions:
+            print(f"  {YELLOW}But it loops more "
+                  f"({best.repetitions} vs {shipped.repetitions}) — "
+                  f"that's what condition_on_previous_text=False is for.{RESET}")
+        print(f"  {DIM}The teacher is a proxy, not truth. Spot-check before "
+              f"changing a default.{RESET}")
+    elif shipped:
+        print(f"\n  {GREEN}The shipped config wins. No change indicated.{RESET}")
+
+
+def _show_vocab() -> None:
+    """Show the vocabulary split by what actually reaches the decoder.
+
+    Whisper can only be biased with ~35 terms (a hard 223-token hotwords cap,
+    and proper nouns cost 5-7 tokens each). Everything past that is not wasted —
+    it still reaches the post-correction LLM — but it does NOT bias decoding,
+    and until now there was no way to see which side of the line a term fell on.
+    """
+    from voiceio.app import _HOTWORDS_TOKEN_BUDGET
+    from voiceio.config import load
+    from voiceio.tokens import count_tokens
+    from voiceio.vocab_stats import VocabStats
+    from voiceio.vocabulary import load_terms, select_terms
+    from voiceio.wizard import BOLD, DIM, GREEN, RESET
+
+    cfg = load()
+    terms = load_terms(cfg.model)
+    if not terms:
+        print("No vocabulary configured.")
+        print("\nTerms are learned automatically: voiceio correct --auto")
+        return
+
+    stats = VocabStats()
+    stats.load()
+    selected = select_terms(terms, token_budget=_HOTWORDS_TOKEN_BUDGET,
+                            model_name=cfg.model.name, stats=stats)
+    used = count_tokens(", ".join(selected), cfg.model.name)
+    sel = set(selected)
+
+    print(f"{BOLD}Biasing the decoder{RESET} "
+          f"{DIM}({used}/{_HOTWORDS_TOKEN_BUDGET} tokens){RESET}")
+    for t in selected:
+        rec = stats.get(t)
+        hits = rec.get("hits", 0)
+        print(f"  {GREEN}●{RESET} {t}" + (f" {DIM}({hits} uses){RESET}" if hits else ""))
+
+    tail = [t for t in terms if t not in sel]
+    if tail:
+        print(f"\n{BOLD}Post-correction only{RESET} "
+              f"{DIM}({len(tail)} terms — past the decoder's token budget,{RESET}")
+        print(f"  {DIM}still used by the correction pass){RESET}")
+        shown = ", ".join(tail[:12])
+        print(f"  {DIM}{shown}{'...' if len(tail) > 12 else ''}{RESET}")
+
+    print(f"\n{len(terms)} term(s): {len(selected)} biasing, {len(tail)} tail")
+
+
 def _cmd_correct(args: argparse.Namespace) -> None:
     """Manage the corrections dictionary."""
     from voiceio.corrections import CorrectionDict
@@ -734,6 +878,10 @@ def _cmd_correct(args: argparse.Namespace) -> None:
         print(f"\n{len(corrections)} correction(s)")
         return
 
+    if args.vocab:
+        _show_vocab()
+        return
+
     if args.remove:
         if cd.remove(args.remove):
             print(f"Removed: {args.remove}")
@@ -936,12 +1084,20 @@ def _cmd_correct_auto(cd, *, full: bool = False, batch: bool = False) -> None:
     # Build lookup for O(1) access to suspicious word metadata
     sw_by_word = {sw.word: sw for sw in suspicious}
 
+    # Correction mining is retired by default ([autocorrect] mine_corrections).
+    # The vocabulary bucket below is unaffected: those terms bias the decoder
+    # and measurably help, whereas mined find/replace rules fired 4 times in 387
+    # while postcorrect applied 288 edits over the same span. Skipping the
+    # correction buckets also skips adjudication — the expensive part, at
+    # votes x ceil(N/25) LLM calls per run.
+    mine_corrections = cfg.autocorrect.mine_corrections
+
     # ── Bucket 1: Auto-fix (high confidence, safety-gated) ──────────────
     # Pairs failing the gate (real word being "corrected", or target that is
     # itself junk) are downgraded to manual review rather than persisted.
     auto_fixed = 0
     downgraded: list[dict] = []
-    if result.auto_fix:
+    if result.auto_fix and mine_corrections:
         gated = []
         for fix in result.auto_fix:
             reason = gate_correction(
@@ -975,10 +1131,13 @@ def _cmd_correct_auto(cd, *, full: bool = False, batch: bool = False) -> None:
         )
 
     # ── Bucket 2: Ask user (ambiguous) ──────────────────────────────────
-    to_review = downgraded + list(result.ask_user)
+    # Empty when correction mining is retired — nothing to adjudicate or review.
+    to_review = (downgraded + list(result.ask_user)) if mine_corrections else []
 
     # If no LLM was used, put all suspicious words into manual review
-    if not has_api and not has_ollama:
+    if not mine_corrections:
+        pass  # correction mining retired — nothing to review or adjudicate
+    elif not has_api and not has_ollama:
         for sw in suspicious:
             to_review.append({
                 "wrong": sw.word,
@@ -1034,8 +1193,13 @@ def _cmd_correct_auto(cd, *, full: bool = False, batch: bool = False) -> None:
         print(f"  {DIM}{len(capped)} lower-frequency item(s) deferred "
               f"to next run{RESET}")
 
-    adj = adjudicate(cfg, to_review, sw_by_word,
-                     vocabulary=vocab_words, language=language)
+    if to_review:
+        adj = adjudicate(cfg, to_review, sw_by_word,
+                         vocabulary=vocab_words, language=language)
+    else:
+        # Nothing to weigh — don't spend votes x ceil(N/25) LLM calls proving it.
+        from voiceio.autocorrect import AdjudicationResult
+        adj = AdjudicationResult()
 
     # Unanimous corrections (already gate-passed inside adjudicate).
     adj_applied = 0

voiceio/config.py

@@ -138,6 +138,17 @@ class AutocorrectConfig:
     # Languages you also dictate in: mined corrections never rewrite words
     # that are real in these (e.g. ["es"] protects Spanish "harina").
     protect_languages: list[str] = field(default_factory=list)
+    # Mine find/replace CORRECTION rules from history. Off by default: measured
+    # over months of real use, mining produced 387 rules of which 4 ever fired
+    # (1%), while the runtime postcorrect pass applied 288 edits over the same
+    # period. Rules are exact-string matches, so they only fire when Whisper
+    # repeats a misrecognition verbatim — and the errors worth fixing are
+    # common words ("nuance" for "neurons") that the safety gate must refuse
+    # anyway. Meanwhile a bad rule is a silent regression: one run learned rules
+    # destroying real Spanish words. Poor odds, real downside, and postcorrect
+    # already does this contextually. Vocabulary mining is unaffected and stays
+    # on — those terms bias the decoder and demonstrably help.
+    mine_corrections: bool = False
 
 
 @dataclass