python-voiceio 0.3.12__tar.gz → 0.4.0__tar.gz

{python_voiceio-0.3.12/python_voiceio.egg-info → python_voiceio-0.4.0}/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 0.3.12
-Summary: Speak → text, locally, instantly.
+Version: 0.4.0
+Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Hugo0/voiceio
 Project-URL: Repository, https://github.com/Hugo0/voiceio
 Project-URL: Issues, https://github.com/Hugo0/voiceio/issues
 Project-URL: Changelog, https://github.com/Hugo0/voiceio/releases
-Keywords: voice,speech-to-text,whisper,linux,windows,dictation,wayland,ibus
+Keywords: voice,speech-to-text,whisper,linux,dictation,wayland,ibus
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: X11 Applications
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: Operating System :: POSIX :: Linux
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Requires-Python: >=3.11
@@ -61,10 +59,18 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://img.shields.io/pepy/dt/python-voiceio)](https://pepy.tech/projects/python-voiceio)
 
-Speak → text, locally, instantly.
+Voice dictation for Linux. Local, yours, and it learns how you speak.
 
 https://github.com/user-attachments/assets/9cf5d1ac-b4bb-4cf8-b775-7a66dc16b376
 
+Open-source, sovereign voice input/output. Your speech is transcribed on your own machine, everything it learns about you stays in local files you own, and it gets better the more you use it.
+
+- **Local & sovereign** — speech is transcribed on-device with [faster-whisper](https://github.com/SYSTRAN/faster-whisper); audio never leaves the machine. Your history, retained audio, corrections, and vocabulary all live in plain local files (JSONL / TOML / txt) you can read, edit, and delete. Zero telemetry. The one honest nuance: two *optional, off-by-default* features send text (never audio) to a cloud LLM you configure yourself — final-transcript polish (`[postcorrect]`) and the weekly correction-mining review.
+- **Improves with use — automatically** — every utterance teaches it your words and names. See [How it learns](#how-it-learns).
+- **Linux-first & hackable** — Wayland/X11, GNOME/KDE/sway/i3, chosen automatically by chain-and-probe backends. It's plain Python you can read in an afternoon and [contribute to](CLAUDE.md).
+
+> **Linux-first.** voiceio is developed and tested daily on Linux (GNOME/Wayland). Windows and macOS ship as **experimental, untested** targets — the code paths exist but are unmaintained and likely broken. See [Experimental platforms](#experimental-platforms).
+
 ## Quick start
 
 ```bash
@@ -102,28 +108,9 @@ voiceio setup
 </details>
 
 <details>
-<summary><strong>Windows</strong></summary>
-
-```powershell
-# Option A: Install with pip (requires Python 3.11+)
-pip install python-voiceio
-voiceio setup
-
-# Option B: Download the installer from GitHub Releases (no Python needed)
-# https://github.com/Hugo0/voiceio/releases
-# Also available as a portable .zip if you prefer no installation.
-```
+<summary><strong>Windows / macOS (experimental)</strong></summary>
 
-Windows uses pynput for hotkeys and text injection. No extra system dependencies required.
-</details>
-
-<details>
-<summary><strong>macOS</strong></summary>
-
-```bash
-pipx install python-voiceio
-voiceio setup
-```
+See [Experimental platforms](#experimental-platforms) below — these builds are untested and unmaintained.
 </details>
 
 <details>
@@ -152,7 +139,35 @@ hotkey → mic capture → whisper (local) → text at cursor
           pre-buffered   streaming        IBus / clipboard
 ```
 
-Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via [faster-whisper](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals.
+Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via [faster-whisper](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals. It runs in real time on a modern CPU and ships with model tiers from `tiny` to `large-v3`.
+
+## How it learns
+
+Most dictation tools transcribe the same way on day 100 as on day 1. voiceio adapts to *you* — your jargon, names, and accent — entirely from data that never leaves your machine.
+
+```mermaid
+flowchart LR
+    subgraph live ["every utterance"]
+        A["🎙️ dictate"] --> B["store audio + raw text\n+ confidence (local)"]
+        A --> C["hotwords + recent context\nbias the Whisper decoder"]
+        A --> D["optional LLM pass fixes\nmisheard proper nouns"]
+    end
+    subgraph weekly ["weekly, in the background"]
+        E["mine history for recurring errors\n→ learn corrections + vocabulary\n(safety-gated, multi-vote)"] --> F["teacher model replays your audio\n→ audits what was learned"]
+        F -->|"bad rule"| G["auto-retired"]
+        F -->|"quality regressed"| H["whole week rolled back"]
+    end
+    B --> E
+    F -->|"confirmed"| C
+```
+
+1. **Capture** — every utterance stores its audio, raw text, and confidence in local files.
+2. **Bias** — your vocabulary and recent context steer the Whisper decoder (hotwords / prompt) on every recording.
+3. **Contextual fix** — an optional LLM pass repairs misheard proper nouns using surrounding context.
+4. **Mine** — a weekly background job scans your history for recurring errors and auto-learns corrections and vocabulary. Multi-vote adjudication and a protected-languages guard (for bilingual users) keep it safe; it never asks you to triage.
+5. **Audit** — a teacher model (a larger Whisper) replays your retained audio to verify what was learned. Bad rules are retired automatically, and a system-level drift metric rolls back an entire week of learning if quality regressed.
+
+Rules are always **probationary, never tenured** — anything that stops helping is dropped. Your only touchpoint is an occasional desktop notification telling you what was learned.
 
 ## Features
 
@@ -202,7 +217,7 @@ voiceio uninstall        Remove all system integrations
 `voiceio setup` handles everything interactively. To tweak later, edit the config file or override at runtime:
 
 - Linux/macOS: `~/.config/voiceio/config.toml`
-- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml`
+- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml` (see [Experimental platforms](#experimental-platforms))
 
 ```bash
 voiceio --model large-v3 --language auto -v
@@ -224,12 +239,12 @@ voiceio logs             # check debug output
 | Hotkey doesn't work on Wayland | `sudo usermod -aG input $USER` then log out and back in |
 | Transcription too slow | Use a smaller model: `voiceio --model tiny` |
 | Want to start fresh | `voiceio uninstall` then `voiceio setup` |
-| Windows: antivirus blocks hotkeys | pynput uses global keyboard hooks — add an exception for voiceio |
-| Windows: no sound feedback | Check `voiceio logs` for audio device info |
-| macOS issues | Experimental — consider [aquavoice.com](https://aquavoice.com/) or contribute a PR |
+| Windows / macOS issues | These platforms are experimental and untested — see [Experimental platforms](#experimental-platforms) |
 
 ## Platform support
 
+voiceio targets **Linux**. That's what it's developed and tested against.
+
 | Platform | Status | Text injection | Hotkeys | Streaming preview |
 |----------|--------|---------------|---------|-------------------|
 | Ubuntu / Debian (GNOME, Wayland) | **Tested daily** | IBus | evdev / GNOME shortcut | Yes |
@@ -237,11 +252,22 @@ voiceio logs             # check debug output
 | Fedora (GNOME) | Supported | IBus | evdev / GNOME shortcut | Yes |
 | Arch Linux | Supported | IBus | evdev | Yes |
 | KDE / Sway / Hyprland | Should work | IBus / ydotool / wtype | evdev | Yes |
-| Windows 10/11 | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
-| macOS | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
 
 voiceio auto-detects your platform and picks the best available backends. Run `voiceio doctor` to see what's working on your system.
 
+## Experimental platforms
+
+Windows and macOS code paths exist, but they are **experimental, untested, and unmaintained** — the maintainer only develops on Linux, so they may be broken at any given time. No parity with Linux is promised. Contributions are welcome, but please don't file bugs expecting a fix.
+
+| Platform | Status | Text injection | Hotkeys | Streaming preview |
+|----------|--------|---------------|---------|-------------------|
+| Windows 10/11 | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+| macOS | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+
+- **Windows:** `pip install python-voiceio` then `voiceio setup` (pynput handles hotkeys + text injection; no system deps). Prebuilt installers may appear on [GitHub Releases](https://github.com/Hugo0/voiceio/releases).
+- **macOS:** `pipx install python-voiceio` then `voiceio setup`. If it doesn't work for you, consider [aquavoice.com](https://aquavoice.com/) or contribute a PR.
+- Config lives at `%LOCALAPPDATA%\voiceio\config\config.toml` (Windows) or `~/.config/voiceio/config.toml` (macOS).
+
 ## Uninstall
 
 ```bash
@@ -275,7 +301,7 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and [open issues](
 - [x] Voice commands — "new line", "new paragraph", "scratch that", punctuation by name
 - [x] Custom vocabulary / personal dictionary (bias Whisper via `initial_prompt`)
 - [x] Smart punctuation & capitalization post-processing
-- [x] Windows support
+- [x] Windows support (experimental, untested)
 - [x] System tray icon with animated states
 - [x] Auto-stop on silence
 

{python_voiceio-0.3.12 → python_voiceio-0.4.0}/README.md

@@ -15,10 +15,18 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://img.shields.io/pepy/dt/python-voiceio)](https://pepy.tech/projects/python-voiceio)
 
-Speak → text, locally, instantly.
+Voice dictation for Linux. Local, yours, and it learns how you speak.
 
 https://github.com/user-attachments/assets/9cf5d1ac-b4bb-4cf8-b775-7a66dc16b376
 
+Open-source, sovereign voice input/output. Your speech is transcribed on your own machine, everything it learns about you stays in local files you own, and it gets better the more you use it.
+
+- **Local & sovereign** — speech is transcribed on-device with [faster-whisper](https://github.com/SYSTRAN/faster-whisper); audio never leaves the machine. Your history, retained audio, corrections, and vocabulary all live in plain local files (JSONL / TOML / txt) you can read, edit, and delete. Zero telemetry. The one honest nuance: two *optional, off-by-default* features send text (never audio) to a cloud LLM you configure yourself — final-transcript polish (`[postcorrect]`) and the weekly correction-mining review.
+- **Improves with use — automatically** — every utterance teaches it your words and names. See [How it learns](#how-it-learns).
+- **Linux-first & hackable** — Wayland/X11, GNOME/KDE/sway/i3, chosen automatically by chain-and-probe backends. It's plain Python you can read in an afternoon and [contribute to](CLAUDE.md).
+
+> **Linux-first.** voiceio is developed and tested daily on Linux (GNOME/Wayland). Windows and macOS ship as **experimental, untested** targets — the code paths exist but are unmaintained and likely broken. See [Experimental platforms](#experimental-platforms).
+
 ## Quick start
 
 ```bash
@@ -56,28 +64,9 @@ voiceio setup
 </details>
 
 <details>
-<summary><strong>Windows</strong></summary>
-
-```powershell
-# Option A: Install with pip (requires Python 3.11+)
-pip install python-voiceio
-voiceio setup
-
-# Option B: Download the installer from GitHub Releases (no Python needed)
-# https://github.com/Hugo0/voiceio/releases
-# Also available as a portable .zip if you prefer no installation.
-```
+<summary><strong>Windows / macOS (experimental)</strong></summary>
 
-Windows uses pynput for hotkeys and text injection. No extra system dependencies required.
-</details>
-
-<details>
-<summary><strong>macOS</strong></summary>
-
-```bash
-pipx install python-voiceio
-voiceio setup
-```
+See [Experimental platforms](#experimental-platforms) below — these builds are untested and unmaintained.
 </details>
 
 <details>
@@ -106,7 +95,35 @@ hotkey → mic capture → whisper (local) → text at cursor
           pre-buffered   streaming        IBus / clipboard
 ```
 
-Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via [faster-whisper](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals.
+Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via [faster-whisper](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals. It runs in real time on a modern CPU and ships with model tiers from `tiny` to `large-v3`.
+
+## How it learns
+
+Most dictation tools transcribe the same way on day 100 as on day 1. voiceio adapts to *you* — your jargon, names, and accent — entirely from data that never leaves your machine.
+
+```mermaid
+flowchart LR
+    subgraph live ["every utterance"]
+        A["🎙️ dictate"] --> B["store audio + raw text\n+ confidence (local)"]
+        A --> C["hotwords + recent context\nbias the Whisper decoder"]
+        A --> D["optional LLM pass fixes\nmisheard proper nouns"]
+    end
+    subgraph weekly ["weekly, in the background"]
+        E["mine history for recurring errors\n→ learn corrections + vocabulary\n(safety-gated, multi-vote)"] --> F["teacher model replays your audio\n→ audits what was learned"]
+        F -->|"bad rule"| G["auto-retired"]
+        F -->|"quality regressed"| H["whole week rolled back"]
+    end
+    B --> E
+    F -->|"confirmed"| C
+```
+
+1. **Capture** — every utterance stores its audio, raw text, and confidence in local files.
+2. **Bias** — your vocabulary and recent context steer the Whisper decoder (hotwords / prompt) on every recording.
+3. **Contextual fix** — an optional LLM pass repairs misheard proper nouns using surrounding context.
+4. **Mine** — a weekly background job scans your history for recurring errors and auto-learns corrections and vocabulary. Multi-vote adjudication and a protected-languages guard (for bilingual users) keep it safe; it never asks you to triage.
+5. **Audit** — a teacher model (a larger Whisper) replays your retained audio to verify what was learned. Bad rules are retired automatically, and a system-level drift metric rolls back an entire week of learning if quality regressed.
+
+Rules are always **probationary, never tenured** — anything that stops helping is dropped. Your only touchpoint is an occasional desktop notification telling you what was learned.
 
 ## Features
 
@@ -156,7 +173,7 @@ voiceio uninstall        Remove all system integrations
 `voiceio setup` handles everything interactively. To tweak later, edit the config file or override at runtime:
 
 - Linux/macOS: `~/.config/voiceio/config.toml`
-- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml`
+- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml` (see [Experimental platforms](#experimental-platforms))
 
 ```bash
 voiceio --model large-v3 --language auto -v
@@ -178,12 +195,12 @@ voiceio logs             # check debug output
 | Hotkey doesn't work on Wayland | `sudo usermod -aG input $USER` then log out and back in |
 | Transcription too slow | Use a smaller model: `voiceio --model tiny` |
 | Want to start fresh | `voiceio uninstall` then `voiceio setup` |
-| Windows: antivirus blocks hotkeys | pynput uses global keyboard hooks — add an exception for voiceio |
-| Windows: no sound feedback | Check `voiceio logs` for audio device info |
-| macOS issues | Experimental — consider [aquavoice.com](https://aquavoice.com/) or contribute a PR |
+| Windows / macOS issues | These platforms are experimental and untested — see [Experimental platforms](#experimental-platforms) |
 
 ## Platform support
 
+voiceio targets **Linux**. That's what it's developed and tested against.
+
 | Platform | Status | Text injection | Hotkeys | Streaming preview |
 |----------|--------|---------------|---------|-------------------|
 | Ubuntu / Debian (GNOME, Wayland) | **Tested daily** | IBus | evdev / GNOME shortcut | Yes |
@@ -191,11 +208,22 @@ voiceio logs             # check debug output
 | Fedora (GNOME) | Supported | IBus | evdev / GNOME shortcut | Yes |
 | Arch Linux | Supported | IBus | evdev | Yes |
 | KDE / Sway / Hyprland | Should work | IBus / ydotool / wtype | evdev | Yes |
-| Windows 10/11 | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
-| macOS | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
 
 voiceio auto-detects your platform and picks the best available backends. Run `voiceio doctor` to see what's working on your system.
 
+## Experimental platforms
+
+Windows and macOS code paths exist, but they are **experimental, untested, and unmaintained** — the maintainer only develops on Linux, so they may be broken at any given time. No parity with Linux is promised. Contributions are welcome, but please don't file bugs expecting a fix.
+
+| Platform | Status | Text injection | Hotkeys | Streaming preview |
+|----------|--------|---------------|---------|-------------------|
+| Windows 10/11 | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+| macOS | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+
+- **Windows:** `pip install python-voiceio` then `voiceio setup` (pynput handles hotkeys + text injection; no system deps). Prebuilt installers may appear on [GitHub Releases](https://github.com/Hugo0/voiceio/releases).
+- **macOS:** `pipx install python-voiceio` then `voiceio setup`. If it doesn't work for you, consider [aquavoice.com](https://aquavoice.com/) or contribute a PR.
+- Config lives at `%LOCALAPPDATA%\voiceio\config\config.toml` (Windows) or `~/.config/voiceio/config.toml` (macOS).
+
 ## Uninstall
 
 ```bash
@@ -229,7 +257,7 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and [open issues](
 - [x] Voice commands — "new line", "new paragraph", "scratch that", punctuation by name
 - [x] Custom vocabulary / personal dictionary (bias Whisper via `initial_prompt`)
 - [x] Smart punctuation & capitalization post-processing
-- [x] Windows support
+- [x] Windows support (experimental, untested)
 - [x] System tray icon with animated states
 - [x] Auto-stop on silence
 

{python_voiceio-0.3.12 → python_voiceio-0.4.0}/pyproject.toml

@@ -4,20 +4,18 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-voiceio"
-version = "0.3.12"
-description = "Speak → text, locally, instantly."
+version = "0.4.0"
+description = "Voice dictation for Linux. Speak → text, locally, instantly."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.11"
 authors = [{ name = "Hugo Montenegro" }]
-keywords = ["voice", "speech-to-text", "whisper", "linux", "windows", "dictation", "wayland", "ibus"]
+keywords = ["voice", "speech-to-text", "whisper", "linux", "dictation", "wayland", "ibus"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Environment :: X11 Applications",
     "Intended Audience :: End Users/Desktop",
     "Operating System :: POSIX :: Linux",
-    "Operating System :: Microsoft :: Windows",
-    "Operating System :: MacOS",
     "Programming Language :: Python :: 3",
     "Topic :: Multimedia :: Sound/Audio :: Speech",
 ]

{python_voiceio-0.3.12 → python_voiceio-0.4.0/python_voiceio.egg-info}/PKG-INFO

@@ -1,20 +1,18 @@
 Metadata-Version: 2.4
 Name: python-voiceio
-Version: 0.3.12
-Summary: Speak → text, locally, instantly.
+Version: 0.4.0
+Summary: Voice dictation for Linux. Speak → text, locally, instantly.
 Author: Hugo Montenegro
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Hugo0/voiceio
 Project-URL: Repository, https://github.com/Hugo0/voiceio
 Project-URL: Issues, https://github.com/Hugo0/voiceio/issues
 Project-URL: Changelog, https://github.com/Hugo0/voiceio/releases
-Keywords: voice,speech-to-text,whisper,linux,windows,dictation,wayland,ibus
+Keywords: voice,speech-to-text,whisper,linux,dictation,wayland,ibus
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: X11 Applications
 Classifier: Intended Audience :: End Users/Desktop
 Classifier: Operating System :: POSIX :: Linux
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
 Requires-Python: >=3.11
@@ -61,10 +59,18 @@ Dynamic: license-file
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Downloads](https://img.shields.io/pepy/dt/python-voiceio)](https://pepy.tech/projects/python-voiceio)
 
-Speak → text, locally, instantly.
+Voice dictation for Linux. Local, yours, and it learns how you speak.
 
 https://github.com/user-attachments/assets/9cf5d1ac-b4bb-4cf8-b775-7a66dc16b376
 
+Open-source, sovereign voice input/output. Your speech is transcribed on your own machine, everything it learns about you stays in local files you own, and it gets better the more you use it.
+
+- **Local & sovereign** — speech is transcribed on-device with [faster-whisper](https://github.com/SYSTRAN/faster-whisper); audio never leaves the machine. Your history, retained audio, corrections, and vocabulary all live in plain local files (JSONL / TOML / txt) you can read, edit, and delete. Zero telemetry. The one honest nuance: two *optional, off-by-default* features send text (never audio) to a cloud LLM you configure yourself — final-transcript polish (`[postcorrect]`) and the weekly correction-mining review.
+- **Improves with use — automatically** — every utterance teaches it your words and names. See [How it learns](#how-it-learns).
+- **Linux-first & hackable** — Wayland/X11, GNOME/KDE/sway/i3, chosen automatically by chain-and-probe backends. It's plain Python you can read in an afternoon and [contribute to](CLAUDE.md).
+
+> **Linux-first.** voiceio is developed and tested daily on Linux (GNOME/Wayland). Windows and macOS ship as **experimental, untested** targets — the code paths exist but are unmaintained and likely broken. See [Experimental platforms](#experimental-platforms).
+
 ## Quick start
 
 ```bash
@@ -102,28 +108,9 @@ voiceio setup
 </details>
 
 <details>
-<summary><strong>Windows</strong></summary>
-
-```powershell
-# Option A: Install with pip (requires Python 3.11+)
-pip install python-voiceio
-voiceio setup
-
-# Option B: Download the installer from GitHub Releases (no Python needed)
-# https://github.com/Hugo0/voiceio/releases
-# Also available as a portable .zip if you prefer no installation.
-```
+<summary><strong>Windows / macOS (experimental)</strong></summary>
 
-Windows uses pynput for hotkeys and text injection. No extra system dependencies required.
-</details>
-
-<details>
-<summary><strong>macOS</strong></summary>
-
-```bash
-pipx install python-voiceio
-voiceio setup
-```
+See [Experimental platforms](#experimental-platforms) below — these builds are untested and unmaintained.
 </details>
 
 <details>
@@ -152,7 +139,35 @@ hotkey → mic capture → whisper (local) → text at cursor
           pre-buffered   streaming        IBus / clipboard
 ```
 
-Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via [faster-whisper](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals.
+Press your hotkey to start recording (1s pre-buffer catches the first syllable). Text streams into the focused app as an underlined preview. Press again to commit. Transcription runs locally via [faster-whisper](https://github.com/SYSTRAN/faster-whisper), text is injected through IBus (any GTK/Qt app) with clipboard fallback for terminals. It runs in real time on a modern CPU and ships with model tiers from `tiny` to `large-v3`.
+
+## How it learns
+
+Most dictation tools transcribe the same way on day 100 as on day 1. voiceio adapts to *you* — your jargon, names, and accent — entirely from data that never leaves your machine.
+
+```mermaid
+flowchart LR
+    subgraph live ["every utterance"]
+        A["🎙️ dictate"] --> B["store audio + raw text\n+ confidence (local)"]
+        A --> C["hotwords + recent context\nbias the Whisper decoder"]
+        A --> D["optional LLM pass fixes\nmisheard proper nouns"]
+    end
+    subgraph weekly ["weekly, in the background"]
+        E["mine history for recurring errors\n→ learn corrections + vocabulary\n(safety-gated, multi-vote)"] --> F["teacher model replays your audio\n→ audits what was learned"]
+        F -->|"bad rule"| G["auto-retired"]
+        F -->|"quality regressed"| H["whole week rolled back"]
+    end
+    B --> E
+    F -->|"confirmed"| C
+```
+
+1. **Capture** — every utterance stores its audio, raw text, and confidence in local files.
+2. **Bias** — your vocabulary and recent context steer the Whisper decoder (hotwords / prompt) on every recording.
+3. **Contextual fix** — an optional LLM pass repairs misheard proper nouns using surrounding context.
+4. **Mine** — a weekly background job scans your history for recurring errors and auto-learns corrections and vocabulary. Multi-vote adjudication and a protected-languages guard (for bilingual users) keep it safe; it never asks you to triage.
+5. **Audit** — a teacher model (a larger Whisper) replays your retained audio to verify what was learned. Bad rules are retired automatically, and a system-level drift metric rolls back an entire week of learning if quality regressed.
+
+Rules are always **probationary, never tenured** — anything that stops helping is dropped. Your only touchpoint is an occasional desktop notification telling you what was learned.
 
 ## Features
 
@@ -202,7 +217,7 @@ voiceio uninstall        Remove all system integrations
 `voiceio setup` handles everything interactively. To tweak later, edit the config file or override at runtime:
 
 - Linux/macOS: `~/.config/voiceio/config.toml`
-- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml`
+- Windows: `%LOCALAPPDATA%\voiceio\config\config.toml` (see [Experimental platforms](#experimental-platforms))
 
 ```bash
 voiceio --model large-v3 --language auto -v
@@ -224,12 +239,12 @@ voiceio logs             # check debug output
 | Hotkey doesn't work on Wayland | `sudo usermod -aG input $USER` then log out and back in |
 | Transcription too slow | Use a smaller model: `voiceio --model tiny` |
 | Want to start fresh | `voiceio uninstall` then `voiceio setup` |
-| Windows: antivirus blocks hotkeys | pynput uses global keyboard hooks — add an exception for voiceio |
-| Windows: no sound feedback | Check `voiceio logs` for audio device info |
-| macOS issues | Experimental — consider [aquavoice.com](https://aquavoice.com/) or contribute a PR |
+| Windows / macOS issues | These platforms are experimental and untested — see [Experimental platforms](#experimental-platforms) |
 
 ## Platform support
 
+voiceio targets **Linux**. That's what it's developed and tested against.
+
 | Platform | Status | Text injection | Hotkeys | Streaming preview |
 |----------|--------|---------------|---------|-------------------|
 | Ubuntu / Debian (GNOME, Wayland) | **Tested daily** | IBus | evdev / GNOME shortcut | Yes |
@@ -237,11 +252,22 @@ voiceio logs             # check debug output
 | Fedora (GNOME) | Supported | IBus | evdev / GNOME shortcut | Yes |
 | Arch Linux | Supported | IBus | evdev | Yes |
 | KDE / Sway / Hyprland | Should work | IBus / ydotool / wtype | evdev | Yes |
-| Windows 10/11 | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
-| macOS | Experimental | pynput / clipboard | pynput | Type-and-correct (no preedit) |
 
 voiceio auto-detects your platform and picks the best available backends. Run `voiceio doctor` to see what's working on your system.
 
+## Experimental platforms
+
+Windows and macOS code paths exist, but they are **experimental, untested, and unmaintained** — the maintainer only develops on Linux, so they may be broken at any given time. No parity with Linux is promised. Contributions are welcome, but please don't file bugs expecting a fix.
+
+| Platform | Status | Text injection | Hotkeys | Streaming preview |
+|----------|--------|---------------|---------|-------------------|
+| Windows 10/11 | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+| macOS | Experimental / untested | pynput / clipboard | pynput | Type-and-correct (no preedit) |
+
+- **Windows:** `pip install python-voiceio` then `voiceio setup` (pynput handles hotkeys + text injection; no system deps). Prebuilt installers may appear on [GitHub Releases](https://github.com/Hugo0/voiceio/releases).
+- **macOS:** `pipx install python-voiceio` then `voiceio setup`. If it doesn't work for you, consider [aquavoice.com](https://aquavoice.com/) or contribute a PR.
+- Config lives at `%LOCALAPPDATA%\voiceio\config\config.toml` (Windows) or `~/.config/voiceio/config.toml` (macOS).
+
 ## Uninstall
 
 ```bash
@@ -275,7 +301,7 @@ Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) and [open issues](
 - [x] Voice commands — "new line", "new paragraph", "scratch that", punctuation by name
 - [x] Custom vocabulary / personal dictionary (bias Whisper via `initial_prompt`)
 - [x] Smart punctuation & capitalization post-processing
-- [x] Windows support
+- [x] Windows support (experimental, untested)
 - [x] System tray icon with animated states
 - [x] Auto-stop on silence
 

{python_voiceio-0.3.12 → python_voiceio-0.4.0}/python_voiceio.egg-info/SOURCES.txt

@@ -7,12 +7,18 @@ python_voiceio.egg-info/dependency_links.txt
 python_voiceio.egg-info/entry_points.txt
 python_voiceio.egg-info/requires.txt
 python_voiceio.egg-info/top_level.txt
+tests/test_adjudicate.py
 tests/test_app_wiring.py
+tests/test_audio_quality.py
+tests/test_audit.py
 tests/test_autocorrect.py
+tests/test_autocorrect_state.py
 tests/test_backend_probes.py
+tests/test_cli.py
 tests/test_clipboard_read.py
 tests/test_commands.py
 tests/test_config.py
+tests/test_correct_batch.py
 tests/test_corrections.py
 tests/test_fallback.py
 tests/test_health.py
@@ -23,11 +29,14 @@ tests/test_llm.py
 tests/test_llm_api.py
 tests/test_numbers.py
 tests/test_platform.py
+tests/test_postcorrect.py
 tests/test_postprocess.py
 tests/test_prebuffer.py
 tests/test_prompt.py
 tests/test_recorder_integration.py
+tests/test_retention.py
 tests/test_robustness.py
+tests/test_snapshots.py
 tests/test_streaming.py
 tests/test_transcriber.py
 tests/test_tts.py
@@ -37,7 +46,9 @@ tests/test_wordfreq.py
 voiceio/__init__.py
 voiceio/__main__.py
 voiceio/app.py
+voiceio/audit.py
 voiceio/autocorrect.py
+voiceio/autocorrect_state.py
 voiceio/backends.py
 voiceio/cli.py
 voiceio/clipboard_read.py
@@ -54,10 +65,13 @@ voiceio/llm_api.py
 voiceio/numbers.py
 voiceio/pidlock.py
 voiceio/platform.py
+voiceio/postcorrect.py
 voiceio/postprocess.py
 voiceio/prompt.py
 voiceio/recorder.py
+voiceio/retention.py
 voiceio/service.py
+voiceio/snapshots.py
 voiceio/streaming.py
 voiceio/transcriber.py
 voiceio/vad.py