DeutschLernen/scripts/ai-setup/README.md

# AI Services Setup Scripts

This directory contains scripts to help you download and configure the AI models required for DeutschLernen's AI services.

## 📦 Required Models

| Service | Model | Size | Purpose |
|---------|-------|------|---------|
| Vosk | `vosk-model-de-0.22` | ~500MB | German speech recognition |
| Coqui TTS | `tts_models/de/deu/fairseq/vits` | ~1.5GB | German text-to-speech |

## 🚀 Quick Setup

Run the master setup script to download and configure all models:

```bash
cd scripts/ai-setup
chmod +x *.sh
./setup-ai-models.sh
```

This will:
1. Check system requirements (wget, unzip, Python 3.8+)
2. Download Vosk German model
3. Install Coqui TTS and pre-download German model
4. Create necessary directories

## 📁 Individual Setup Scripts

### Download Vosk Model Only

```bash
./download-vosk-model.sh [target-directory]
```

**Default target:** `./models/vosk`

**Example:**
```bash
./download-vosk-model.sh /opt/ai-models/vosk
```

**What it does:**
- Creates target directory
- Downloads vosk-model-de-0.22.zip
- Extracts the model
- Cleans up the zip file
- Verifies model files exist

### Download Coqui TTS Model Only

```bash
./download-coqui-model.sh [model-name] [audio-storage-path]
```

**Default model:** `tts_models/de/deu/fairseq/vits`
**Default audio path:** `./tmp/tts-audio`

**Example:**
```bash
./download-coqui-model.sh tts_models/de/deu/fairseq/vits /opt/ai-models/tts-audio
```

**What it does:**
- Checks Python version (3.8+)
- Installs Coqui TTS via pip
- Creates audio storage directory
- Pre-downloads the German model
- Outputs configuration for appsettings.json

## 📝 Configuration

After running the setup scripts, update your `appsettings.json`:

### Vosk Configuration
```json
{
  "Vosk": {
    "PythonPath": "python3",
    "ModelPath": "./models/vosk/vosk-model-de-0.22",
    "SampleRate": 16000,
    "TimeoutSeconds": 30,
    "BeamWidth": 20
  }
}
```

### Coqui 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

### Test Vosk Installation
```bash
python3 -c "import vosk; print('Vosk OK')"
python3 -c "from vosk import Model; Model('./models/vosk/vosk-model-de-0.22'); print('Model OK')"
```

### Test Coqui TTS Installation
```bash
python3 -c "from TTS.api import TTS; print('Coqui TTS OK')"
python3 -c "from TTS.api import TTS; tts = TTS(model_name='tts_models/de/deu/fairseq/vits'); tts.tts_to_file(text='Hallo', file_path='/tmp/test.wav'); print('TTS Generation OK')"
```

## ⚠️ Requirements

### System Requirements
- **Disk Space:** ~2GB total
  - Vosk model: ~500MB
  - Coqui model: ~1.5GB
  - Temporary files: ~50-100MB

### Software Requirements
| Tool | Version | Installation |
|------|---------|-------------|
| Python | 3.8+ | https://www.python.org/downloads/ |
| pip | Latest | Included with Python |
| wget | Any | `sudo apt-get install wget` |
| unzip | Any | `sudo apt-get install unzip` |

### Python Packages
```bash
pip install vosk TTS
```

## 🛠️ Master Setup Script Options

```bash
# Download all models
./setup-ai-models.sh

# Download only Vosk model
./setup-ai-models.sh --vosk-only

# Download only Coqui TTS model
./setup-ai-models.sh --coqui-only

# Use custom directory
./setup-ai-models.sh --models-dir /opt/ai-models

# Show help
./setup-ai-models.sh --help
```

## 🔄 Model Management

### Model Locations
- Vosk models: https://alphacephei.com/vosk/models
- Coqui TTS models: https://github.com/coqui-ai/TTS/wiki/Multilingual-support

### Alternative Models

#### Vosk (German)
- `vosk-model-de-0.22` - Recommended (~500MB, good accuracy)
- `vosk-model-small-de-0.15` - Smaller (~50MB, lower accuracy)
- `vosk-model-de-0.42` - Larger (~1.5GB, better accuracy)

#### Coqui TTS (German)
- `tts_models/de/deu/fairseq/vits` - Recommended
- `tts_models/de/common-voice/fairseq-vits` - Alternative
- `tts_models/multilingual/multi-dataset/fairseq-vits` - Multi-language

## 🐛 Troubleshooting

| Issue | Solution |
|-------|----------|
| `ModuleNotFoundError: vosk` | Run `pip install vosk` |
| `ModuleNotFoundError: TTS` | Run `pip install TTS` |
| Model directory not found | Verify ModelPath in appsettings.json |
| Permission denied | Use absolute paths or check write permissions |
| Out of disk space | Free up space or use smaller models |
| Python not found | Install Python 3.8+ |
| wget not found | Install with `sudo apt-get install wget` |
| unzip not found | Install with `sudo apt-get install unzip` |

## 📚 Additional Documentation

- [AI Services Feature Plan](../../docs/features/ai-services.md)
- [Vosk Documentation](https://alphacephei.com/vosk/)
- [Coqui TTS GitHub](https://github.com/coqui-ai/TTS)
- [Mistral AI API](https://docs.mistral.ai/)