feat(recognition): add custom dictionary support

[GrahamJenkins]

Description

Adds custom dictionary support using a UTF-8 text file with one term or phrase per line.

• Adds a Dictionary settings page with enablement, file selection, and live status.
• Uses ~/.config/vocalinux/dictionary.txt by default.
• Re-reads the file before every transcription so changes apply without restarting.
• Supports Whisper and whisper.cpp while preserving the existing Advanced initial prompt.
• Warns and safely ignores the dictionary when VOSK is selected.
• Adds a session-only --dictionary-file PATH override without modifying config.json.
• Treats missing, unreadable, invalid, or non-UTF-8 files as unavailable without interrupting dictation.

The accessibility scanner discussed separately is intentionally not included in this PR.

Related Discussion

#483

Type of Change

• New feature
• Documentation update
• Test update

Verification

• 191 focused dictionary, CLI, settings, and recognition-manager tests pass.
• Black, locked isort, flake8 critical checks, and git diff --check pass.
• Human-tested on Ubuntu 24.04 with whisper.cpp: custom dictionary terms were used successfully during dictation.

The full local test run is environment-limited: an existing IBus test cannot bind its Unix socket in the sandbox after 551 tests pass, and an installer Vulkan test later times out. The focused feature suite passes and upstream CI remains the final full-suite check.

Checklist

• Code follows the project style.
• Documentation is updated.
• Tests cover the new behavior.
• Human testing is complete.

Additional Notes

The custom dictionary is disabled by default. For whisper.cpp, the existing Advanced initial prompt remains first and dictionary terms are appended after it.

[netlify]

✅ Deploy Preview for voca-linux canceled.

Name	Link
🔨 Latest commit	90ba737
🔍 Latest deploy log	https://app.netlify.com/projects/voca-linux/deploys/6a97a69bd58176000969e35a

[github-actions]

Thanks @GrahamJenkins. A maintainer will review it.

---

Meanwhile, connect with us:

[greptile-apps]

Greptile Summary

Adds configurable, live-reloaded custom dictionary support for Whisper-family recognition engines.

• Adds persistent settings and a session-only CLI override for dictionary files.
• Integrates dictionary prompts with Whisper and whisper.cpp while preserving whisper.cpp’s advanced prompt.
• Adds safe handling for unavailable or malformed files and warns when the unsupported VOSK engine is selected.
• Documents the feature and adds focused manager, CLI, recognition, and settings tests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/vocalinux/dictionary_manager.py	Implements live dictionary loading, path and status handling, prompt limits, and safe malformed-UTF-8 behavior.
src/vocalinux/speech_recognition/recognition_manager.py	Injects refreshed dictionary prompts into Whisper and whisper.cpp and emits a one-time VOSK incompatibility warning.
src/vocalinux/ui/settings_dialog.py	Adds typed dictionary settings controls, session-override locking, and live status refresh.
src/vocalinux/main.py	Adds the session-only dictionary CLI override and wires the dictionary manager into recognition.
tests/test_dictionary_manager.py	Covers live reloads, malformed UTF-8, prompt composition and clearing, transient configuration, and VOSK behavior.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as CLI / Settings
    participant DM as DictionaryManager
    participant RM as RecognitionManager
    participant Engine as Whisper Engine
    User->>CLI: Configure or override dictionary path
    CLI->>DM: Create/update dictionary configuration
    RM->>DM: Build prompt before transcription
    DM->>DM: Re-read UTF-8 dictionary file
    DM-->>RM: Current terms or no prompt
    RM->>Engine: Transcribe with composed prompt
    Engine-->>User: Recognized text

Loading

_{Reviews (2): Last reviewed commit: "fix(dictionary): handle invalid UTF-8 sa..." | Re-trigger Greptile}

[greptile-apps]

Dictionary signatures lack type hints

The new dictionary UI methods and callbacks omit parameter or return annotations, expanding the untyped interface surface contrary to the repository requirement that every function signature include type hints. The same pattern also appears in the new dictionary test helpers.

Context Used: AGENTS.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[GrahamJenkins]

Fixed in 90ba737. The new Dictionary settings handlers and test helpers now have explicit type annotations.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 85.38462% with 19 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/vocalinux/dictionary_manager.py	83.16%	13 Missing and 4 partials ⚠️
src/vocalinux/main.py	71.42%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[GrahamJenkins]

Cross-posting on both issues, #767 #768 functionally overlap, two separate implementations. Maintainers should compare each on their merits and decide accordingly.