Add Voxtral Realtime STT support via voxmlx

[vr000m]

Summary

• Add Voxtral Realtime STT support via voxmlx, optimized for Apple Silicon (MLX)
• Segmented mode (STT_SERVICE=voxtral): Batch transcription after VAD detects end of speech. ~0.30s per utterance at 480ms delay.
• Streaming mode (STT_SERVICE=voxtral-streaming): Incremental encode/decode during speech via background thread. ~0.16s from end-of-turn to final transcription.
• Configurable delay via VOXTRAL_DELAY_MS env var (default 480, must be multiple of 80)
• Add .env.example with all supported environment variables and STT/TTS configuration docs to README

Changes

New files

• src/pipecat_mcp_server/processors/voxtral_stt.py — Segmented STT (extends SegmentedSTTService)
• src/pipecat_mcp_server/processors/voxtral_streaming_stt.py — Streaming STT (extends STTService) with background thread for MLX operations
• .env.example — Documented environment variables for STT, TTS, and transport configuration

Modified files

• src/pipecat_mcp_server/agent.py — STT service selection via STT_SERVICE env var, _parse_voxtral_delay_ms() validation, load_dotenv(override=False)
• src/pipecat_mcp_server/agent_ipc.py — load_dotenv(override=False) to avoid overwriting explicit env vars
• pyproject.toml — Add voxmlx dependency (macOS only)
• .gitignore — Add uv.lock, add !.env.example exception
• README.md — Add Configuration section with STT/TTS options tables

Architecture (streaming mode)

Pipeline (async):                          Background thread (sync):
  AudioRawFrame                             while running:
    → process_audio_frame()                   drain audio_in_queue → pending_audio
      → audio_in_queue.put(samples)           encode (mel_step → encode_step)
      → drain token_out_queue                 decode (prefill → decode_steps)
        → push InterimTranscriptionFrame      token_out_queue.put(token_id or EOS)
        → push TranscriptionFrame             sleep(0.01)

Key design decisions

• Background thread for MLX ops (GPU-bound, would block async event loop)
• queue.Queue for thread-safe async↔sync communication
• _flush_until_eos() polls token queue after VAD stop to ensure final transcript is emitted
• mx.clear_cache() after every mx.eval() to prevent MLX memory pool leaks
• O(1) incremental token decoding via _partial_text accumulator
• Thread crash handling via _THREAD_ERROR sentinel

Test plan

macOS (Apple Silicon)

• Set STT_SERVICE=voxtral — verify segmented mode transcribes correctly
• Set STT_SERVICE=voxtral-streaming — verify streaming mode emits interim + final transcriptions
• Verify memory stability over multiple utterances (no growth beyond ~65MB)
• Test interruption mid-sentence — verify clean state reset
• Test invalid VOXTRAL_DELAY_MS values — verify validation and rounding
• Default (no STT_SERVICE) — verify Whisper MLX fallback still works

Non-darwin (Linux)

• Verify default STT (WhisperSTTService with faster-distil-whisper-large-v3) still works
• Verify voxmlx dependency is not pulled in (conditional on sys_platform == 'darwin')
• Verify setting STT_SERVICE=voxtral or voxtral-streaming fails gracefully on Linux (import error from voxmlx/MLX)