Metadata-Version: 2.4
Name: thunderclap
Version: 0.3.0
Summary: Voice assistant framework — STT/TTS/wake-word. No API keys.
Author: Sasquatch Builder
License: MIT
Platform: Linux
Requires-Python: >=3.10
Requires-Dist: requests>=2.32
Requires-Dist: pyyaml>=6.0
Requires-Dist: faster-whisper>=1.0 ; extra == "stt"
Requires-Dist: ctranslate2>=4.0 ; extra == "stt"
Requires-Dist: piper-tts>=1.0 ; extra == "tts"
Requires-Dist: onnxruntime>=1.17 ; extra == "tts"
Requires-Dist: pyaudio>=0.2.14 ; extra == "audio"
Requires-Dist: numpy>=1.26 ; extra == "audio"
Requires-Dist: openwakeword>=0.6.0 ; extra == "wakeword"
Requires-Dist: pyaudio>=0.2.14 ; extra == "all"
Requires-Dist: numpy>=1.26 ; extra == "all"
Requires-Dist: openwakeword>=0.6.0 ; extra == "all"
Requires-Dist: faster-whisper>=1.0 ; extra == "all"
Requires-Dist: ctranslate2>=4.0 ; extra == "all"
Requires-Dist: piper-tts>=1.0 ; extra == "all"
Requires-Dist: onnxruntime>=1.17 ; extra == "all"
Provides-Extra: stt
Provides-Extra: tts
Provides-Extra: audio
Provides-Extra: wakeword
Provides-Extra: all
Description: # ThunderClap - Voice Command System
        
        ## Overview
        Full voice integration system for senbot with wake word, STT, TTS, and conversational AI.
        
        ## Hardware
        - **Speaker**: USB Speaker Bar (detected via ALSA/PulseAudio)
        - **Microphone**: USB Audio Interface
        - **Status**: ✅ Audio playback verified working (2026-03-01)
        
        ## Docker Containers
        
        ### STT (Speech-to-Text)
        - **Image**: `linuxserver/faster-whisper`
        - **Port**: 8001
        - **API**: HTTP REST
        - **Model**: whisper-base (default)
        - **Status**: ✅ Running
        
        ### TTS (Text-to-Speech)
        - **Image**: `rhasspy/wyoming-piper`
        - **Port**: 10200
        - **API**: Wyoming protocol (HTTP + UDP events)
        - **Voice**: en_US-lessac-medium.onnx
        - **Status**: ✅ Running
        
        ## Components
        
        ### Wake Word
        - **Engine**: Porcupine or Snowboy
        - **Wake Word**: "Hey Senbot" (configurable)
        
        ### Speech-to-Text (STT)
        - **Engine**: Faster Whisper (CTranslate2 optimized Whisper)
        - **Model**: whisper-base
        - **API Endpoint**: http://localhost:8001
        
        ### Text-to-Speech (TTS)
        - **Engine**: Piper TTS via Wyoming
        - **Voice**: en_US-lessac-medium.onnx
        - **API Endpoint**: http://localhost:10200
        
        ### NLP/Intent
        - **LLM**: Ollama (qwen3:14b, llama3:8b)
        - **Mode**: Conversational or command-based
        
        ## Architecture
        
        ```
        [USB Microphone] -> [STT Docker:8001] -> [Ollama LLM] -> [TTS Docker:10200] -> [USB Speaker]
        ```
        
        ## Configuration
        See `src/config.py`
        
        ## Model Upgrade Options (For Future Review)
        - **STT**: Distil-Whisper Large V3 (5-6x faster, ~5GB VRAM, MIT license)
        - **STT**: Canary Qwen 2.5B (best WER 5.63%, ~6GB VRAM)
        - **TTS**: Coqui TTS (alternative to Piper)
        
        ## Status
        - IN PROGRESS
        - Audio hardware working ✅
        - Docker containers running ✅
        - Python modules implemented ✅
        - End-to-end test pending
        # Senbot Voice System
        
        Full voice integration for senbot with wake word, speech-to-text, LLM processing, and text-to-speech.
        
        ## Features
        
        - **Wake Word Detection** - Always listening for "Senbot" or custom wake words
        - **Microphone Capture** - High-quality audio capture from system microphones
        - **Speech-to-Text** - Convert voice to text using Whisper (via Ollama)
        - **LLM Processing** - Process commands through Ollama (llama3, qwen, etc.)
        - **Text-to-Speech** - Speak responses using Piper TTS
        - **Conversational Mode** - Multi-turn dialogue without repeat wake word
        - **Recording Mode** - Save voice sessions to files
        
        ## Architecture
        
        ```
        ┌─────────────────────────────────────────────────────────────┐
        │                    VOICE SYSTEM                              │
        ├─────────────────────────────────────────────────────────────┤
        │  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
        │  │ Wake Word│───▶│ Microphone│───▶│   STT    │              │
        │  │ Listener │    │  Capture  │    │ (Whisper)│              │
        │  └──────────┘    └──────────┘    └────┬─────┘              │
        │                                        │                    │
        │                                        ▼                    │
        │  ┌──────────┐    ┌──────────┐    ┌──────────┐             │
        │  │  Speaker │◀───│   TTS    │◀───│    LLM   │             │
        │  │  Output  │    │ (Piper)  │    │ (Ollama) │             │
        │  └──────────┘    └──────────┘    └──────────┘             │
        ├─────────────────────────────────────────────────────────────┤
        │  Modes: Wake | Listen | Speak | Record                      │
        └─────────────────────────────────────────────────────────────┘
        ```
        
        ## Installation
        
        ```bash
        # Install dependencies
        pip install pyaudio numpy pvporcupine requests
        
        # Install Piper TTS
        # See: https://github.com/rhasspy/piper
        
        # Start Ollama with whisper model
        ollama serve &
        ollama pull whisper
        ```
        
        ## Usage
        
        ### CLI
        
        ```bash
        # Start voice system
        python -m senbot.voice.cli start
        
        # Check status
        python -m senbot.voice.cli status
        
        # List audio devices
        python -m senbot.voice.cli devices
        
        # Test speak
        python -m senbot.voice.cli speak --text "Hello world"
        
        # Stop
        python -m senbot.voice.cli stop
        ```
        
        ### Python API
        
        ```python
        from senbot.voice import get_voice_processor
        
        # Get processor
        vp = get_voice_processor()
        
        # Start
        vp.start()
        
        # Status
        print(vp.get_status())
        
        # Speak something
        vp.speak("Hello! I am online.")
        
        # Stop
        vp.stop()
        ```
        
        ## Configuration
        
        Edit `config.yaml`:
        
        ```yaml
        voice:
          wake_words:
            - senbot
            - computer
          sample_rate: 16000
          command_timeout: 5
          conversational_mode: false
          
        ollama:
          url: http://localhost:11434
          model: llama3:8b
          
        tts:
          model: en_US-lessac-medium
        ```
        
        ## Requirements
        
        - Python 3.8+
        - PyAudio
        - Ollama running with:
          - whisper (STT)
          - llama3:8b or qwen3:14b (LLM)
        - Piper TTS (optional, for local TTS)
        
        ## Status
        
        🔄 IN PROGRESS - Core pipeline built, need to:
        - [ ] Test with actual audio hardware
        - [ ] Download whisper model to Ollama
        - [ ] Set up Piper TTS server
        - [ ] Add proper error handling
        - [ ] Add configuration file
Description-Content-Type: text/markdown
