[NOTICKET] Update readme

README.md

@@ -9,14 +9,16 @@ pinned: false
 
 # Voice Agent Service
 
-Real-time voice agent backend with WebSocket-based STT (AssemblyAI) and TTS (Cartesia). Accepts audio stream from client, detects wake word, and streams back synthesized speech.
+Real-time voice agent backend dengan WebSocket-based STT (Deepgram) dan TTS (Cartesia). Menerima audio stream dari client, mendeteksi wake word, lalu streaming kembali synthesized speech.
+
+**Versi saat ini: Phase 1 (Echo Mode)** — teks setelah wake word langsung di-echo melalui TTS. Phase 2 (LLM + RAG) direncanakan namun belum diimplementasi.
 
 ## Requirements
 
 - Python 3.11+
 - [uv](https://docs.astral.sh/uv/getting-started/installation/)
-- AssemblyAI API key (free tier)
-- Cartesia API key + Voice ID (free tier)
+- Deepgram API key
+- Cartesia API key + Voice ID
 
 ## Setup
 
@@ -32,11 +34,21 @@ cp .env.example .env
 
 Edit `.env` dan isi API keys:
 ```env
-ASSEMBLYAI_API_KEY=your_key
+DEEPGRAM_API_KEY=your_key
 CARTESIA_API_KEY=your_key
 CARTESIA_VOICE_ID=your_voice_id
 ```
 
+**Konfigurasi opsional:**
+```env
+CARTESIA_MODEL=sonic-3               # Default: sonic-3
+DEEPGRAM_LANGUAGE=id                 # Default: id (Indonesian)
+DEEPGRAM_ENDPOINTING_MS=300          # Default: 300ms
+DEEPGRAM_UTTERANCE_END_MS=2000       # Default: 2000ms
+SAMPLE_RATE=16000                    # Default: 16000 Hz
+WAKE_WORD=Hai EMA                    # Default: "Hai EMA"
+```
+
 ## Run
 
 ```bash
@@ -62,16 +74,21 @@ Expected response:
 }
 ```
 
-**WebSocket test (kirim audio WAV, terima TTS response):**
+Status `degraded` (HTTP 503) akan dikembalikan jika API keys tidak lengkap.
+
+**WebSocket test — kirim audio WAV, terima TTS response:**
 ```bash
-uv run python test_client.py path/to/audio.wav
+uv run python test_client.py --test audio --wav path/to/audio.wav --save-tts output.wav
 ```
 
-> File WAV harus dalam format: 16kHz, 16-bit, mono PCM.
+> File WAV harus dalam format: **16kHz, 16-bit, mono PCM**.
 
-Output audio response akan disimpan ke `output.pcm`. Untuk memutarnya:
+**Test spesifik:**
 ```bash
-ffplay -f s16le -ar 16000 -ac 1 output.pcm
+uv run python test_client.py --test health      # Health check
+uv run python test_client.py --test ping        # Heartbeat ping/pong
+uv run python test_client.py --test interrupt   # Cancel ongoing TTS
+uv run python test_client.py --test stop        # Graceful disconnect
 ```
 
 **Connectivity check (tanpa file audio):**
@@ -79,7 +96,11 @@ ffplay -f s16le -ar 16000 -ac 1 output.pcm
 uv run python test_client.py
 ```
 
-Mengirim 3 detik silence untuk memverifikasi koneksi WebSocket berhasil.
+**Konversi audio M4A ke WAV:**
+```bash
+uv run python convert_audio.py                     # Konversi semua file di playground/mp4/
+uv run python convert_audio.py path/to/file.m4a   # Konversi satu file
+```
 
 ## Docker
 
@@ -95,10 +116,95 @@ docker run -p 7860:7860 --env-file .env voice-agent
 
 ## Wake Word
 
-Default wake word: **"hi voice agent"** (case-insensitive)
+Default wake word: **"Hai EMA"** (bahasa Indonesia, case-insensitive)
+
+Contoh: ucapkan _"Hai EMA, apa kabar?"_ → agent akan membalas dengan TTS _"apa kabar"_.
+
+Dapat dikonfigurasi via environment variable `WAKE_WORD`.
+
+## Arsitektur
+
+### Alur saat ini (Phase 1 — Echo)
+
+```
+Client Audio Stream (PCM 16kHz 16-bit mono)
+    ↓
+Deepgram STT (nova-2, real-time streaming)
+    ↓
+Wake Word Detection
+    ↓
+Echo Response
+    ↓
+Cartesia TTS (streaming chunks)
+    ↓
+Client Audio Playback
+```
+
+### Alur yang direncanakan (Phase 2 — LLM + RAG)
+
+```
+Client Audio Stream
+    ↓
+Deepgram STT
+    ↓
+Wake Word Detection
+    ↓
+PDF Knowledge Base Retrieval (belum diimplementasi)
+    ↓
+LLM Answer Generation (belum diimplementasi)
+    ↓
+Cartesia TTS
+    ↓
+Client Audio Playback
+```
+
+## WebSocket Protocol
+
+**Endpoint:** `ws://localhost:7860/ws/voice`
 
-Contoh: ucapkan _"Hi Voice Agent, what time is it?"_ → agent akan membalas dengan TTS _"what time is it"_.
+**Client → Server:**
 
-## API Contract
+| Type | Format | Keterangan |
+|------|--------|------------|
+| Binary | PCM audio chunk | Audio 16kHz, 16-bit, mono |
+| Text | `{"action": "ping"}` | Heartbeat keep-alive |
+| Text | `{"action": "stop"}` | Graceful disconnect |
+| Text | `{"action": "interrupt"}` | Cancel ongoing TTS |
+
+**Server → Client:**
+
+| Type | Format | Keterangan |
+|------|--------|------------|
+| Binary | PCM audio chunk | TTS response audio |
+| Text | `{"event": "transcript", "text": "..."}` | Hasil STT |
+| Text | `{"event": "reply", "text": "..."}` | Teks setelah wake word |
+| Text | `{"event": "tts_end"}` | TTS selesai |
+| Text | `{"event": "interrupted"}` | TTS dibatalkan |
+| Text | `{"event": "pong"}` | Response ping |
+| Text | `{"event": "error", "code": "...", "message": "..."}` | Error |
 
 Lihat [API_CONTRACT.md](API_CONTRACT.md) untuk dokumentasi lengkap WebSocket protocol.
+
+## Struktur Project
+
+```
+├── src/
+│   ├── config.py              # Konfigurasi & environment variables
+│   ├── pipeline.py            # Core voice pipeline (STT → Wake Word → TTS)
+│   ├── stt/
+│   │   ├── deepgram_client.py # Deepgram real-time STT (aktif)
+│   │   └── assemblyai_client.py # AssemblyAI STT (alternatif, tidak digunakan)
+│   ├── tts/
+│   │   └── cartesia_client.py # Cartesia TTS streaming
+│   ├── llm/
+│   │   └── answerer.py        # LLM answer generation (Phase 2, belum diimplementasi)
+│   └── knowledge/
+│       └── loader.py          # PDF loader & RAG (Phase 2, belum diimplementasi)
+├── main.py                    # FastAPI entry point & WebSocket handler
+├── test_client.py             # Test client
+├── convert_audio.py           # Konverter M4A → WAV
+├── playground/                # Audio sample dan output TTS
+├── Dockerfile
+├── .env.example
+└── API_CONTRACT.md
+```