diff --git a/GermanApp/Infrastructure/Configuration/CoquiConfig.cs b/GermanApp/Infrastructure/Configuration/CoquiConfig.cs index a459952..2b25bbb 100644 --- a/GermanApp/Infrastructure/Configuration/CoquiConfig.cs +++ b/GermanApp/Infrastructure/Configuration/CoquiConfig.cs @@ -3,6 +3,16 @@ namespace GermanApp.Infrastructure.Configuration; /// /// Configuration settings for Coqui TTS service. /// This is part of the Infrastructure layer. +/// +/// Setup Instructions: +/// 1. Install Python 3.8+: https://www.python.org/downloads/ +/// 2. Install Coqui TTS: pip install TTS +/// 3. Coqui will automatically download the model on first use based on ModelName +/// 4. Recommended German model: tts_models/de/deu/fairseq/vits +/// 5. Set AudioStoragePath to a directory with write permissions +/// +/// Note: Models require ~1.5GB disk space. First run will download the model automatically. +/// Alternative: Pre-download with: python -m TTS.server --model_name tts_models/de/deu/fairseq/vits /// public class CoquiConfig { diff --git a/GermanApp/Infrastructure/Configuration/VoskConfig.cs b/GermanApp/Infrastructure/Configuration/VoskConfig.cs index 2c51291..3bb80ee 100644 --- a/GermanApp/Infrastructure/Configuration/VoskConfig.cs +++ b/GermanApp/Infrastructure/Configuration/VoskConfig.cs @@ -3,6 +3,16 @@ namespace GermanApp.Infrastructure.Configuration; /// /// Configuration settings for Vosk speech recognition service. /// This is part of the Infrastructure layer. +/// +/// Setup Instructions: +/// 1. Install Python 3.8+: https://www.python.org/downloads/ +/// 2. Install Vosk: pip install vosk +/// 3. Download German model: +/// wget https://alphacephei.com/vosk/models/vosk-model-de-0.22.zip +/// unzip vosk-model-de-0.22.zip +/// 4. Set ModelPath to the extracted directory (e.g., /models/vosk-model-de-0.22) +/// +/// Note: Model requires ~500MB disk space /// public class VoskConfig { diff --git a/GermanApp/Infrastructure/Services/TtsService.cs b/GermanApp/Infrastructure/Services/TtsService.cs index e307a11..f72a087 100644 --- a/GermanApp/Infrastructure/Services/TtsService.cs +++ b/GermanApp/Infrastructure/Services/TtsService.cs @@ -25,10 +25,59 @@ public class TtsService : ITtsService _config = config.Value; _logger = logger; + // Validate configuration + ValidateConfiguration(); + // Ensure audio storage directory exists Directory.CreateDirectory(_config.AudioStoragePath); } + /// + /// Validates TTS configuration on startup. + /// + /// Thrown when configuration is invalid + private void ValidateConfiguration() + { + if (string.IsNullOrWhiteSpace(_config.PythonPath)) + { + _logger.LogError("Coqui PythonPath is not configured"); + throw new InvalidOperationException( + "Coqui PythonPath is not configured. Please set Coqui:PythonPath in appsettings.json"); + } + + if (string.IsNullOrWhiteSpace(_config.ModelName)) + { + _logger.LogError("Coqui ModelName is not configured"); + throw new InvalidOperationException( + "Coqui ModelName is not configured. Please set Coqui:ModelName in appsettings.json. " + + "Example: tts_models/de/deu/fairseq/vits"); + } + + if (string.IsNullOrWhiteSpace(_config.AudioStoragePath)) + { + _logger.LogError("Coqui AudioStoragePath is not configured"); + throw new InvalidOperationException( + "Coqui AudioStoragePath is not configured. Please set Coqui:AudioStoragePath in appsettings.json"); + } + + if (_config.MaxTextLength <= 0) + { + _logger.LogError("Coqui MaxTextLength must be positive"); + throw new InvalidOperationException( + "Coqui MaxTextLength must be greater than 0"); + } + + if (_config.TimeoutSeconds <= 0) + { + _logger.LogError("Coqui TimeoutSeconds must be positive"); + throw new InvalidOperationException( + "Coqui TimeoutSeconds must be greater than 0"); + } + + _logger.LogInformation("Coqui TTS configuration validated: Model={ModelName}, Storage={AudioStoragePath}", + _config.ModelName, _config.AudioStoragePath); + } + /// /// Generates audio from text. /// diff --git a/GermanApp/Infrastructure/Services/VoskService.cs b/GermanApp/Infrastructure/Services/VoskService.cs index b9a5a4c..3e960b6 100644 --- a/GermanApp/Infrastructure/Services/VoskService.cs +++ b/GermanApp/Infrastructure/Services/VoskService.cs @@ -24,6 +24,37 @@ public class VoskService : IVoskService { _config = config.Value; _logger = logger; + + // Validate model path on startup + ValidateModelPath(); + } + + /// + /// Validates that the Vosk model directory exists and is accessible. + /// + /// Thrown when model path is not configured + /// Thrown when model directory doesn't exist + private void ValidateModelPath() + { + if (string.IsNullOrWhiteSpace(_config.ModelPath)) + { + _logger.LogError("Vosk ModelPath is not configured. Please set Vosk:ModelPath in appsettings.json"); + throw new InvalidOperationException( + "Vosk model path is not configured. " + + "Please download vosk-model-de-0.22 from https://alphacephei.com/vosk/models " + + "and set the ModelPath in appsettings.json"); + } + + if (!Directory.Exists(_config.ModelPath)) + { + _logger.LogError("Vosk model directory not found: {ModelPath}", _config.ModelPath); + throw new DirectoryNotFoundException( + $"Vosk model directory not found: {_config.ModelPath}. " + + "Please download vosk-model-de-0.22 from https://alphacephei.com/vosk/models " + + "and extract it to the configured path"); + } + + _logger.LogInformation("Vosk model directory validated: {ModelPath}", _config.ModelPath); } /// diff --git a/docs/features/ai-services.md b/docs/features/ai-services.md index 0f4508a..9a55075 100644 --- a/docs/features/ai-services.md +++ b/docs/features/ai-services.md @@ -139,6 +139,158 @@ For production deployment via Woodpecker: - `.woodpecker.yml` - CI/CD pipeline with secrets injection - `docker-compose.yml` - Docker Compose with environment variable placeholders +### 📥 AI Model Setup Guide + +This section provides step-by-step instructions for downloading and configuring the AI models required for Vosk and Coqui TTS services. + +#### Vosk Speech Recognition Model (vosk-model-de-0.22) + +**Size:** ~500MB + +**Download and Setup:** + +```bash +# 1. Create models directory +mkdir -p models/vosk + +# 2. Download the German model +wget https://alphacephei.com/vosk/models/vosk-model-de-0.22.zip -P models/vosk/ + +# 3. Extract the model +cd models/vosk/ +unzip vosk-model-de-0.22.zip +cd ../../ + +# 4. Verify the model directory structure +# You should have: models/vosk/vosk-model-de-0.22/ +# With files: model, ivector, etc. +``` + +**Configuration:** +```json +{ + "Vosk": { + "PythonPath": "python3", + "ModelPath": "./models/vosk-model-de-0.22", + "SampleRate": 16000, + "TimeoutSeconds": 30, + "BeamWidth": 20 + } +} +``` + +**Verification:** +```bash +# Test Vosk installation +python3 -c "import vosk; print('Vosk installed successfully')" + +# Test model loading +python3 -c "from vosk import Model; Model('./models/vosk-model-de-0.22'); print('Model loaded successfully')" +``` + +**Alternative Models:** +- `vosk-model-small-de-0.15` - Smaller model (~50MB), less accurate +- `vosk-model-de-0.42` - Larger model (~1.5GB), more accurate + +--- + +#### Coqui TTS Model (tts_models/de/deu/fairseq/vits) + +**Size:** ~1.5GB (auto-downloaded on first use) + +**Download and Setup:** + +**Option 1: Auto-download (Recommended)** +The Coqui TTS library will automatically download the model on first use. Just ensure: +1. Python 3.8+ is installed +2. `pip install TTS` +3. Sufficient disk space (~1.5GB) + +**Option 2: Pre-download Model** +```bash +# 1. Install Coqui TTS +pip install TTS + +# 2. Pre-download the German model (optional) +python3 -c "from TTS.api import TTS; TTS(model_name='tts_models/de/deu/fairseq/vits')" +# This will download the model to ~/.local/share/tts/ +``` + +**Configuration:** +```json +{ + "Coqui": { + "PythonPath": "python3", + "ModelName": "tts_models/de/deu/fairseq/vits", + "OutputFormat": "wav", + "SampleRate": 22050, + "AudioStoragePath": "./tmp/tts-audio", + "MaxTextLength": 5000, + "TimeoutSeconds": 60 + } +} +``` + +**Verification:** +```bash +# Test Coqui TTS installation +python3 -c "from TTS.api import TTS; print('Coqui TTS installed successfully')" + +# Test text-to-speech generation +python3 -c "from TTS.api import TTS; tts = TTS(model_name='tts_models/de/deu/fairseq/vits'); tts.tts_to_file(text='Hallo Welt', file_path='/tmp/test.wav'); print('TTS generation successful')" +``` + +**Alternative German Models:** +- `tts_models/de/common-voice/fairseq-vits` - Alternative German model +- `tts_models/multilingual/multi-dataset/fairseq-vits` - Multi-language model + +**Troubleshooting:** + +| Issue | Solution | +|-------|----------| +| ModuleNotFoundError: vosk | Run `pip install vosk` | +| ModuleNotFoundError: TTS | Run `pip install TTS` | +| Model directory not found | Verify ModelPath points to extracted model directory | +| Permission denied | Use absolute paths or ensure write permissions | +| Out of disk space | Free up space or use smaller model | +| Python not found | Install Python 3.8+ or set correct PythonPath | + +--- + +#### Mistral API Configuration + +**Required:** Valid Mistral API key + +**Setup:** +1. Get API key from https://console.mistral.ai/ +2. Add to appsettings.json: + +```json +{ + "Mistral": { + "ApiKey": "your-api-key-here", + "BaseUrl": "https://api.mistral.ai/v1/", + "DefaultModel": "mistral-medium", + "TimeoutSeconds": 30, + "MaxRetries": 3, + "RateLimitPerMinute": 10, + "EnableCaching": true, + "CacheTTLMinutes": 60, + "CircuitBreakerFailureThreshold": 5, + "CircuitBreakerResetMinutes": 1 + } +} +``` + +**Verification:** +```bash +# Test Mistral API connection +curl -X POST "https://api.mistral.ai/v1/completions" \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"model": "mistral-medium", "prompt": "Say hello", "max_tokens": 10}' +``` + ### Data Flow #### Story Generation Flow @@ -200,7 +352,7 @@ For production deployment via Woodpecker: - Resilient to API failures (retry, rate limiting, circuit breaker, caching) - Testable with mocked HTTP client -### Phase 1: Configuration ### Phase 1: Configuration ### Phase 1: Configuration ### Phase 1: Configuration & Interfaces (2 hours) Interfaces (2 hours) ✅ Interfaces (2 hours) ✅ Interfaces (2 hours) ✅ +### Phase 1: Configuration ### Phase 1: Configuration ### Phase 1: Configuration ### Phase 1: Configuration ### Phase 1: Configuration & Interfaces (2 hours) Interfaces (2 hours) ✅ Interfaces (2 hours) ✅ Interfaces (2 hours) ✅ Interfaces (2 hours) ✅ - [x] Add AI configuration section to appsettings.json - [x] Create configuration classes (MistralConfig, VoskConfig, CoquiConfig) - [x] Define service interfaces (IMistralService, IVoskService, ITtsService) @@ -219,7 +371,7 @@ For production deployment via Woodpecker: ### Phase 3: Vosk Speech Recognition (2-3 hours) ✅ - [x] Create VoskService implementation - [x] Set up Vosk Python environment (Process.Start based) -- [ ] Download and configure German model (requires ~1.5GB disk space) (vosk-model-de-0.22) +- [ ] Download and configure vosk-model-de-0.22 (~500MB) - [x] Implement audio processing - [x] Handle different audio formats (byte[], file, stream) - [x] Add error handling for recognition failures @@ -228,7 +380,7 @@ For production deployment via Woodpecker: ### Phase 4: Coqui TTS Integration (2-3 hours) ✅ - [x] Create TtsService implementation - [x] Set up Coqui TTS Python environment (Process.Start based) -- [ ] Download and configure German model (requires ~1.5GB disk space) +- [ ] Download and configure Coqui German model (~1.5GB) - [x] Implement audio generation - [x] Add audio file management (storage, cleanup) - [x] Create audio serving endpoints (/api/tts/generate, etc.) @@ -239,7 +391,7 @@ For production deployment via Woodpecker: - [ ] Create WritingFeedbackService (uses MistralService) - [ ] Create SpeechExerciseService (uses VoskService) - [ ] Create AudioGenerationService (uses TtsService) -- [ ] Add health checks for all AI services +- [x] Add health checks for all AI services (AiServicesHealthCheck.cs) - [ ] Implement fallback mechanisms for service failures ### Milestones