python-voiceio 0.5.0__tar.gz → 0.6.0__tar.gz

{python_voiceio-0.5.0/python_voiceio.egg-info → python_voiceio-0.6.0}/PKG-INFO

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

{python_voiceio-0.5.0 → python_voiceio-0.6.0}/pyproject.toml

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

{python_voiceio-0.5.0 → python_voiceio-0.6.0/python_voiceio.egg-info}/PKG-INFO

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

{python_voiceio-0.5.0 → python_voiceio-0.6.0}/tests/test_postcorrect.py

@@ -161,3 +161,119 @@ def test_pipeline_runs_postcorrect_only_on_final():
         )
         assert text == "Crisp chat is the best tool"
         assert not abort
+
+
+# ── wall-clock deadline ──────────────────────────────────────────────────
+
+
+def test_deadline_exceeded_keeps_original():
+    """A chat call slower than timeout_secs is abandoned at the deadline."""
+    import time as _time
+    cfg = _cfg()
+    cfg.postcorrect.timeout_secs = 0.2
+
+    def slow_chat(*a, **kw):
+        _time.sleep(2.0)
+        return "Crisp chat is the tool"
+
+    pc = PostCorrector(cfg)
+    with patch("voiceio.llm_api.chat", side_effect=slow_chat):
+        t0 = _time.monotonic()
+        assert pc.correct("Chris chat is the tool") == "Chris chat is the tool"
+        elapsed = _time.monotonic() - t0
+    assert elapsed < 1.0  # returned at the deadline, not after the full call
+    assert pc.last_secs is not None
+
+
+def test_within_deadline_applies_correction():
+    cfg = _cfg()
+    cfg.postcorrect.timeout_secs = 5.0
+    pc = PostCorrector(cfg)
+    with patch("voiceio.llm_api.chat", return_value="Crisp chat is the tool"):
+        assert pc.correct("Chris chat is the tool") == "Crisp chat is the tool"
+
+
+# ── before/after pair persistence ────────────────────────────────────────
+
+
+def _read_pairs(path):
+    import json
+    return [json.loads(line) for line in path.read_text().splitlines()]
+
+
+def test_applied_correction_recorded(tmp_path, monkeypatch):
+    import voiceio.postcorrect as pcmod
+    from voiceio import config as cfgmod
+    pairs = tmp_path / "pairs.jsonl"
+    monkeypatch.setattr(cfgmod, "POSTCORRECT_PAIRS_PATH", pairs)
+    pc = PostCorrector(_cfg())
+    with patch("voiceio.llm_api.chat", return_value="Crisp chat is the tool"):
+        pc.correct("Chris chat is the tool")
+    entries = _read_pairs(pairs)
+    assert len(entries) == 1
+    assert entries[0]["outcome"] == "applied"
+    assert entries[0]["before"] == "Chris chat is the tool"
+    assert entries[0]["after"] == "Crisp chat is the tool"
+    assert entries[0]["secs"] is not None
+
+
+def test_rejected_rewrite_recorded(tmp_path, monkeypatch):
+    from voiceio import config as cfgmod
+    pairs = tmp_path / "pairs.jsonl"
+    monkeypatch.setattr(cfgmod, "POSTCORRECT_PAIRS_PATH", pairs)
+    pc = PostCorrector(_cfg())
+    with patch("voiceio.llm_api.chat", return_value="Completely different rewritten sentence with many other words entirely"):
+        out = pc.correct("Chris chat is the tool")
+    assert out == "Chris chat is the tool"
+    entries = _read_pairs(pairs)
+    assert len(entries) == 1
+    assert entries[0]["outcome"].startswith("rejected")
+
+
+def test_no_recording_when_disabled(tmp_path, monkeypatch):
+    from voiceio import config as cfgmod
+    pairs = tmp_path / "pairs.jsonl"
+    monkeypatch.setattr(cfgmod, "POSTCORRECT_PAIRS_PATH", pairs)
+    cfg = _cfg()
+    cfg.data.capture_intermediates = False
+    pc = PostCorrector(cfg)
+    with patch("voiceio.llm_api.chat", return_value="Crisp chat is the tool"):
+        pc.correct("Chris chat is the tool")
+    assert not pairs.exists()
+
+
+def test_hung_request_blocks_next_call_not_thread_pileup(tmp_path, monkeypatch):
+    """A worker abandoned at the deadline makes the NEXT call skip the LLM."""
+    import threading as _threading
+    import time as _time
+    from voiceio import config as cfgmod
+    monkeypatch.setattr(cfgmod, "POSTCORRECT_PAIRS_PATH", tmp_path / "pairs.jsonl")
+    cfg = _cfg()
+    cfg.postcorrect.timeout_secs = 0.1
+    pc = PostCorrector(cfg)
+    release = _threading.Event()
+
+    def hung_chat(*a, **kw):
+        release.wait(5)
+        return "x"
+
+    with patch("voiceio.llm_api.chat", side_effect=hung_chat) as mock_chat:
+        assert pc.correct("Chris chat is the tool") == "Chris chat is the tool"
+        assert mock_chat.call_count == 1
+        # Second call while the first worker is still hung: no new thread
+        assert pc.correct("Chris chat is the tool") == "Chris chat is the tool"
+        assert mock_chat.call_count == 1
+    release.set()
+    entries = _read_pairs(tmp_path / "pairs.jsonl")
+    assert [e["outcome"] for e in entries] == ["timeout", "skipped_busy"]
+
+
+def test_recorded_context_is_effective_context(tmp_path, monkeypatch):
+    from voiceio import config as cfgmod
+    monkeypatch.setattr(cfgmod, "POSTCORRECT_PAIRS_PATH", tmp_path / "pairs.jsonl")
+    pc = PostCorrector(_cfg())
+    pc.set_context(title="Stale Window")
+    with patch("voiceio.llm_api.chat", return_value="Crisp chat is the tool"):
+        pc.correct("Chris chat is the tool", context="Fresh Window")
+    entries = _read_pairs(tmp_path / "pairs.jsonl")
+    assert entries[0]["context"] == "Fresh Window"

{python_voiceio-0.5.0 → python_voiceio-0.6.0}/tests/test_retention.py

@@ -97,3 +97,72 @@ class TestHistoryExtra:
         entry = json.loads(p.read_text())
         assert entry["text"] == "hello"
         assert entry["ts"] != 0
+
+
+# ── intermediate data capture + disk floor ──────────────────────────────
+
+
+class TestAppendJsonl:
+    def test_appends_lines(self, tmp_path):
+        from voiceio import retention
+        p = tmp_path / "pairs.jsonl"
+        retention.append_jsonl(p, {"a": 1})
+        retention.append_jsonl(p, {"b": 2})
+        import json
+        lines = [json.loads(line) for line in p.read_text().splitlines()]
+        assert lines == [{"a": 1}, {"b": 2}]
+
+    def test_never_raises_on_bad_entry(self, tmp_path):
+        from voiceio import retention
+        retention.append_jsonl(tmp_path / "x.jsonl", {"bad": object()})  # not JSON-able
+
+
+class TestSaveTrace:
+    def test_writes_when_enabled(self, tmp_path, monkeypatch):
+        from voiceio import retention
+        from voiceio.config import DataConfig
+        monkeypatch.setattr(retention, "TRACES_PATH", tmp_path / "trace.jsonl")
+        retention.save_trace(DataConfig(), {"ts": 1, "passes": []})
+        assert (tmp_path / "trace.jsonl").exists()
+
+    def test_skips_when_disabled(self, tmp_path, monkeypatch):
+        from voiceio import retention
+        from voiceio.config import DataConfig
+        monkeypatch.setattr(retention, "TRACES_PATH", tmp_path / "trace.jsonl")
+        retention.save_trace(DataConfig(capture_intermediates=False), {"ts": 1})
+        assert not (tmp_path / "trace.jsonl").exists()
+
+
+class TestDiskFloor:
+    def test_save_audio_skips_below_floor(self, monkeypatch):
+        import numpy as np
+        from voiceio import retention
+        from voiceio.config import DataConfig
+        monkeypatch.setattr(retention, "_free_gb", lambda p: 1.0)
+        name = retention.save_audio(
+            np.zeros(1600, dtype=np.float32), 0.0, DataConfig(min_free_gb=5.0),
+        )
+        assert name is None
+
+    def test_save_audio_ok_above_floor(self, tmp_path, monkeypatch):
+        import numpy as np
+        from voiceio import retention
+        from voiceio.config import DataConfig
+        monkeypatch.setattr(retention, "RECORDINGS_DIR", tmp_path)
+        monkeypatch.setattr(retention, "_free_gb", lambda p: 100.0)
+        name = retention.save_audio(
+            np.zeros(1600, dtype=np.float32), 0.0, DataConfig(min_free_gb=5.0),
+        )
+        assert name is not None and (tmp_path / name).exists()
+
+    def test_prune_shrinks_budget_below_floor(self, tmp_path, monkeypatch):
+        from voiceio import retention
+        from voiceio.config import DataConfig
+        monkeypatch.setattr(retention, "RECORDINGS_DIR", tmp_path)
+        monkeypatch.setattr(retention, "_free_gb", lambda p: 1.0)
+        for i in range(4):
+            (tmp_path / f"r{i}.wav").write_bytes(b"x" * 1000)
+        retention.prune(DataConfig(max_audio_mb=1024, min_free_gb=5.0))
+        # Budget halved from 4000 bytes total → keep <= 2000 bytes
+        remaining = sum(p.stat().st_size for p in tmp_path.glob("*.wav"))
+        assert remaining <= 2000

{python_voiceio-0.5.0 → python_voiceio-0.6.0}/tests/test_streaming.py

@@ -5,7 +5,7 @@ import json
 import threading
 import time
 from pathlib import Path
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, patch
 
 from voiceio.typers.base import TyperBackend
 
@@ -566,7 +566,7 @@ class TestWorkerLoop:
         call_count = 0
         transcriber = MagicMock()
 
-        def slow_transcribe(audio, final=False):
+        def slow_transcribe(audio, final=False, context=None):
             nonlocal call_count
             call_count += 1
             time.sleep(0.2)
@@ -649,3 +649,221 @@ class TestOnInterim:
         s, _ = self._make_session(None)
         s._apply_correction("Hello world")
         assert s.interim_text == "Hello world"
+
+
+# --- incremental finalization (segment freezing) ---
+
+SR = 16000
+
+
+def _silent(secs):
+    return np.zeros(int(SR * secs), dtype=np.float32)
+
+
+def _loud(secs):
+    return np.full(int(SR * secs), 0.5, dtype=np.float32)
+
+
+class TestSegmentFreeze:
+    def _make_session(self, freeze_secs=2.0):
+        recorder = MagicMock()
+        recorder.sample_rate = SR
+        transcriber = MagicMock()
+        transcriber.last_segments = []
+        session = StreamingSession(
+            transcriber=transcriber,
+            typer=MagicMock(spec=TyperBackend),
+            recorder=recorder,
+            freeze_secs=freeze_secs,
+        )
+        return session, transcriber, recorder
+
+    def test_freeze_triggers_on_long_silent_tail(self):
+        s, tr, rec = self._make_session(freeze_secs=2.0)
+        rec.get_audio_so_far.return_value = _silent(3)
+        tr.transcribe.return_value = "hello there friend"
+        s._transcribe_and_apply()
+        assert s._frozen_raw == "hello there friend"
+        assert s._frozen_samples == SR * 3
+        # Freeze pass gets beam search (final=True)
+        assert tr.transcribe.call_args.kwargs["final"] is True
+
+    def test_no_freeze_when_tail_is_speech(self):
+        s, tr, rec = self._make_session(freeze_secs=2.0)
+        rec.get_audio_so_far.return_value = _loud(3)
+        tr.transcribe.return_value = "hello there friend"
+        s._transcribe_and_apply()
+        assert s._frozen_raw == ""
+        assert s._frozen_samples == 0
+        assert tr.transcribe.call_args.kwargs["final"] is False
+
+    def test_no_freeze_when_disabled(self):
+        s, tr, rec = self._make_session(freeze_secs=0)
+        rec.get_audio_so_far.return_value = _silent(30)
+        tr.transcribe.return_value = "hello there friend"
+        s._transcribe_and_apply()
+        assert s._frozen_raw == ""
+
+    def test_interim_after_freeze_decodes_only_tail(self):
+        s, tr, rec = self._make_session(freeze_secs=2.0)
+        s._frozen_raw = "hello there friend"
+        s._frozen_samples = SR * 3
+        rec.get_audio_so_far.return_value = np.concatenate([_silent(3), _loud(1.5)])
+        tr.transcribe.return_value = "how are"
+        s._transcribe_and_apply()
+        sent_audio = tr.transcribe.call_args.args[0]
+        assert len(sent_audio) == SR * 1.5  # only the un-frozen tail
+        assert "hello there friend" in tr.transcribe.call_args.kwargs["context"]
+        assert s._typed_text == "hello there friend how are"
+
+    def test_final_decodes_only_tail_and_merges(self):
+        s, tr, rec = self._make_session(freeze_secs=2.0)
+        s._frozen_raw = "hello there friend"
+        s._frozen_samples = SR * 3
+        s._final_audio = np.concatenate([_silent(3), _loud(2)])
+        tr.transcribe.return_value = "how are you"
+        s._transcribe_and_apply(min_seconds=0.5, final=True)
+        sent_audio = tr.transcribe.call_args.args[0]
+        assert len(sent_audio) == SR * 2
+        assert s.raw_final_text == "hello there friend how are you"
+        assert s.final_latency["frozen_secs"] == 3.0
+        assert s.final_latency["tail_secs"] == 2.0
+        assert s._typed_text == "hello there friend how are you"
+
+    def test_final_with_silent_tail_commits_frozen_text(self):
+        s, tr, rec = self._make_session(freeze_secs=2.0)
+        s._frozen_raw = "hello there friend"
+        s._frozen_samples = SR * 3
+        # Tiny trailing tail is still decoded (a clipped last word must not
+        # be dropped); here it is genuinely silent, so frozen text commits.
+        s._final_audio = np.concatenate([_silent(3), _silent(0.1)])
+        tr.transcribe.return_value = ""
+        s._transcribe_and_apply(min_seconds=0.5, final=True)
+        tr.transcribe.assert_called_once()
+        assert s.raw_final_text == "hello there friend"
+        assert s._typed_text == "hello there friend"
+
+    def test_frozen_segments_accumulate_into_final(self):
+        s, tr, rec = self._make_session(freeze_secs=2.0)
+        rec.get_audio_so_far.return_value = _silent(3)
+        tr.transcribe.return_value = "hello there friend"
+        tr.last_segments = [{"text": "hello there friend", "avg_logprob": -0.2}]
+        s._transcribe_and_apply()  # freeze pass
+        s._final_audio = np.concatenate([_silent(3), _loud(2)])
+        tr.transcribe.return_value = "how are you"
+        tr.last_segments = [{"text": "how are you", "avg_logprob": -0.3}]
+        s._transcribe_and_apply(min_seconds=0.5, final=True)
+        assert [seg["text"] for seg in s.final_segments] == [
+            "hello there friend", "how are you",
+        ]
+
+    def test_abort_discards_frozen_text(self):
+        s, tr, rec = self._make_session(freeze_secs=2.0)
+        s._frozen_raw = "hello there friend"
+        s._frozen_samples = SR * 3
+        s._typed_text = "hello there friend"
+        rec.get_audio_so_far.return_value = np.concatenate([_silent(3), _loud(1.5)])
+        tr.transcribe.return_value = "scratch that"
+        with patch("voiceio.postprocess.apply_pipeline", return_value=("", True)):
+            s._transcribe_and_apply()
+        assert s._frozen_raw == ""
+        assert s._typed_text == ""
+        # Frozen boundary advances so the wiped audio is never re-decoded
+        assert s._frozen_samples == SR * 4.5
+
+
+class TestDecodeTrace:
+    def test_trace_records_pass_kinds(self):
+        recorder = MagicMock()
+        recorder.sample_rate = SR
+        transcriber = MagicMock()
+        transcriber.last_segments = []
+        s = StreamingSession(
+            transcriber=transcriber,
+            typer=MagicMock(spec=TyperBackend),
+            recorder=recorder,
+            freeze_secs=2.0,
+        )
+        transcriber.transcribe.return_value = "hello there friend"
+        rec_audio = _silent(3)
+        recorder.get_audio_so_far.return_value = rec_audio
+        s._transcribe_and_apply()  # freeze pass
+        s._final_audio = np.concatenate([_silent(3), _loud(1)])
+        transcriber.transcribe.return_value = "bye"
+        s._transcribe_and_apply(min_seconds=0.5, final=True)
+        kinds = [p["kind"] for p in s.trace]
+        assert kinds == ["freeze", "final"]
+        assert s.trace[0]["text"] == "hello there friend"
+        assert s.trace[1]["tail_secs"] == 1.0
+        assert all("secs" in p for p in s.trace)
+
+
+# --- code-review regressions: decode failures must never lose audio/text ---
+
+class TestDecodeFailureSafety:
+    def _make_session(self, freeze_secs=2.0, typer_spec=TyperBackend):
+        recorder = MagicMock()
+        recorder.sample_rate = SR
+        transcriber = MagicMock()
+        transcriber.last_segments = []
+        s = StreamingSession(
+            transcriber=transcriber,
+            typer=MagicMock(spec=typer_spec),
+            recorder=recorder,
+            freeze_secs=freeze_secs,
+        )
+        return s, transcriber, recorder
+
+    def test_failed_freeze_decode_does_not_advance_boundary(self):
+        s, tr, rec = self._make_session()
+        rec.get_audio_so_far.return_value = _silent(3)
+        tr.transcribe.side_effect = RuntimeError("decode timed out")
+        s._transcribe_and_apply()
+        assert s._frozen_samples == 0  # audio NOT discarded
+        assert s._frozen_raw == ""
+
+    def test_failed_final_decode_commits_interim_text(self):
+        s, tr, rec = self._make_session(typer_spec=StreamingTyper)
+        s._frozen_raw = "hello there friend"
+        s._frozen_samples = SR * 3
+        s._typed_text = "hello there friend how are you"  # shown via preedit
+        s._final_audio = np.concatenate([_silent(3), _loud(2)])
+        tr.transcribe.side_effect = RuntimeError("decode timed out")
+        s._transcribe_and_apply(min_seconds=0.5, final=True)
+        # Interim text committed, not char-diffed down to frozen-only text
+        s._typer.commit_text.assert_called_once_with("hello there friend how are you")
+        assert s.final_latency.get("decode_failed") is True
+
+    def test_final_decodes_sub_300ms_tail(self):
+        s, tr, rec = self._make_session()
+        s._frozen_raw = "hello there friend"
+        s._frozen_samples = SR * 3
+        s._final_audio = np.concatenate([_silent(3), _loud(0.25)])
+        tr.transcribe.return_value = "yes"
+        s._transcribe_and_apply(min_seconds=0.5, final=True)
+        tr.transcribe.assert_called_once()  # short last word not dropped
+        assert s.raw_final_text == "hello there friend yes"
+
+    def test_empty_interim_decode_keeps_display(self):
+        s, tr, rec = self._make_session(freeze_secs=0)
+        s._frozen_raw = "hello there friend"
+        s._frozen_samples = SR * 3
+        s._typed_text = "hello there friend how are"
+        rec.get_audio_so_far.return_value = np.concatenate([_silent(3), _loud(1.5)])
+        tr.transcribe.return_value = ""  # transient decoder flake
+        s._transcribe_and_apply()
+        s._typer.type_text.assert_not_called()
+        s._typer.delete_chars.assert_not_called()
+        assert s._typed_text == "hello there friend how are"
+
+    def test_quiet_mic_speech_is_not_silence(self):
+        from voiceio.streaming import _tail_ends_in_silence
+        # Continuous speech on a low-gain mic: quiet in absolute terms but
+        # uniform — trailing window matches overall level, so NOT a pause.
+        quiet_speech = np.full(SR * 3, 0.005, dtype=np.float32)
+        assert not _tail_ends_in_silence(quiet_speech, SR)
+        # Same quiet mic with a real trailing pause IS a pause.
+        with_pause = np.concatenate([
+            np.full(int(SR * 2.5), 0.005, dtype=np.float32), _silent(0.5),
+        ])
+        assert _tail_ends_in_silence(with_pause, SR)

{python_voiceio-0.5.0 → python_voiceio-0.6.0}/tests/test_transcriber.py

@@ -130,3 +130,39 @@ class TestRestartBudgetReset:
 
         with pytest.raises(RuntimeError, match="crashed"):
             t._ensure_worker()
+
+
+class TestTimeoutRaises:
+    """Timeout/invalid response raise TranscriptionError (never fake silence)."""
+
+    def _make(self):
+        from voiceio.transcriber import Transcriber
+        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())
+        return t, mock_proc
+
+    def test_timeout_raises_and_clears_segments(self):
+        import numpy as np
+        import pytest
+        from voiceio.transcriber import TranscriptionError
+        t, mock_proc = self._make()
+        t.last_segments = [{"text": "stale"}]
+        with patch.object(t, "_read_with_timeout", return_value=None), \
+             patch.object(t, "_kill_worker"), patch.object(t, "_ensure_worker"):
+            with pytest.raises(TranscriptionError):
+                t.transcribe(np.zeros(16000, dtype=np.float32))
+        assert t.last_segments == []
+
+    def test_invalid_response_raises_and_clears_segments(self):
+        import numpy as np
+        import pytest
+        from voiceio.transcriber import TranscriptionError
+        t, mock_proc = self._make()
+        t.last_segments = [{"text": "stale"}]
+        with patch.object(t, "_read_with_timeout", return_value="not json{"):
+            with pytest.raises(TranscriptionError):
+                t.transcribe(np.zeros(16000, dtype=np.float32))
+        assert t.last_segments == []

python_voiceio-0.6.0/voiceio/__init__.py

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

{python_voiceio-0.5.0 → python_voiceio-0.6.0}/voiceio/app.py

@@ -393,6 +393,7 @@ class VoiceIO:
                 voice_input_prefix=self._voice_input_prefix,
                 on_typer_broken=self._on_typer_broken,
                 on_interim=self._on_interim_text,
+                freeze_secs=self.cfg.output.streaming_freeze_secs,
             )
             self._session.start()
         log.info("Recording... press [%s] again to stop", self.cfg.hotkey.key)
@@ -545,6 +546,16 @@ class VoiceIO:
                 duration=elapsed,
                 extra=extra,
             )
+            from voiceio import retention
+            retention.save_trace(self.cfg.data, {
+                "ts": time.time(),
+                "audio": extra.get("audio"),
+                "duration": round(elapsed, 2),
+                "latency": latency,
+                # Snapshot: a timed-out worker join means the thread may
+                # still be appending while we serialize.
+                "passes": list(session.trace),
+            })
         log.info("Streaming done (%.1fs): '%s'", elapsed, final_text)
         # Release the IBus input source now that the final commit is done.
         # Generation-checked inside: if a newer recording started, it already

{python_voiceio-0.5.0 → python_voiceio-0.6.0}/voiceio/config.py

@@ -33,6 +33,11 @@ PID_PATH = LOG_DIR / "voiceio.pid"
 # and the retired-rule state consulted by the mining side.
 CORRECTIONS_AUDIT_PATH = LOG_DIR / "corrections_audit.jsonl"
 METRICS_PATH = LOG_DIR / "metrics.jsonl"
+# Intermediate pipeline data kept for debugging/profiling and future training:
+# per-pass streaming decode traces and postcorrect before/after pairs. These
+# live in their own JSONL files (not the rotating log) so they survive.
+TRACES_PATH = LOG_DIR / "streaming_trace.jsonl"
+POSTCORRECT_PAIRS_PATH = LOG_DIR / "postcorrect_pairs.jsonl"
 SNAPSHOTS_DIR = CONFIG_DIR / "snapshots"
 AUDIT_STATE_PATH = CONFIG_DIR / "audit_state.json"
 AUTOCORRECT_STATE_PATH = CONFIG_DIR / "autocorrect_state.json"
@@ -79,6 +84,11 @@ class OutputConfig:
     punctuation_cleanup: bool = True
     number_conversion: bool = True
     voice_input_prefix: str = ""           # e.g. "[voice]" — empty disables
+    # Incremental finalization: once the un-finalized audio tail grows past
+    # this many seconds AND ends in silence, beam-decode and freeze it during
+    # recording, so interim passes and the stop-time final decode only cover
+    # the short remaining tail. 0 disables (full re-decode at stop).
+    streaming_freeze_secs: float = 25.0
     # Mirror transcribed text to the system clipboard so it can be pasted:
     #   "off"   — never
     #   "final" — the corrected final text, once ready
@@ -179,7 +189,14 @@ class DataConfig:
     """
     retain_audio: bool = True
     max_audio_mb: int = 4096   # prune oldest recordings beyond this
+    # Never let retention squeeze the disk: skip saving and prune harder
+    # when the filesystem has less than this much free space.
+    min_free_gb: float = 5.0
     capture_context: bool = True  # best-effort active-window title
+    # Per-pass streaming decode traces + postcorrect before/after pairs
+    # (streaming_trace.jsonl / postcorrect_pairs.jsonl) for debugging,
+    # profiling, and future fine-tuning.
+    capture_intermediates: bool = True
 
 
 @dataclass
@@ -283,6 +300,8 @@ def _content_files() -> list[Path]:
         HISTORY_PATH,
         CORRECTIONS_AUDIT_PATH,
         METRICS_PATH,
+        TRACES_PATH,
+        POSTCORRECT_PAIRS_PATH,
         AUDIT_STATE_PATH,
         AUTOCORRECT_STATE_PATH,
         CONSENT_PATH,