aillom-vox-client 1.0.0

package/docs/ASTERISK.md

@@ -0,0 +1,411 @@
+# 📞 Asterisk 23 Integration Guide - AillomVox
+
+Complete guide for integrating **Asterisk 23** with **AillomVox** for real-time Voice AI calls.
+
+---
+
+## 🎯 Overview
+
+AillomVox provides **two integration architectures** for Asterisk:
+
+### 1. **Direct Mode** (Simple)
+```
+Asterisk → AudioSocket → AillomVox Gateway → AI Provider
+```
+✅ Simple voice conversations  
+❌ No client tools (transfer, AMI control)
+
+### 2. **Middleware Mode** (Advanced)
+```
+Asterisk → AudioSocket → Node.js Middleware → AillomVox Gateway
+                ↓ AMI/ARI
+```
+✅ Client tools enabled (transfer, hangup, dial)  
+✅ Full Asterisk control from AI
+
+---
+
+## 📋 Prerequisites
+
+### Asterisk Requirements
+- **Asterisk 23** (or 18+)
+- **AudioSocket** module compiled and enabled
+- **API Key** for AillomVox gateway
+
+### Verify AudioSocket Module
+```bash
+asterisk -rx "module show like audiosocket"
+```
+
+Expected output:
+```
+Module                         Description
+res_audiosocket.so             AudioSocket
+```
+
+If not loaded:
+```bash
+# Load module
+asterisk -rx "module load res_audiosocket"
+
+# Make it persistent
+echo "load = res_audiosocket.so" >> /etc/asterisk/modules.conf
+```
+
+---
+
+## 🔐 Authentication
+
+AillomVox uses **API Key** authentication for security and usage tracking.
+
+### Getting Your API Key
+
+Get your API key from the AillomVox dashboard or contact support.
+
+### Storing API Key
+
+Store in `extensions.conf`:
+
+```ini
+[globals]
+AILLOM_API_KEY=your-api-key-here
+```
+
+---
+
+## 🏗️ Architecture 1: Direct Mode (Simple)
+
+### When to Use
+- Simple AI voice conversations
+- No need to transfer calls or control Asterisk
+- Just want AI to answer and respond
+
+### Dialplan Configuration
+
+```ini
+[from-internal]
+
+; Call extension 6000 to talk to AI
+exten => 6000,1,NoOp(AillomVox Direct Mode)
+ same => n,Set(WS_URL=ws://vox.aillom.com/ws?apiKey=${AILLOM_API_KEY})
+ same => n,Set(CONFIG={"provider":"aillomvox","voice":"Heitor","language":"pt-BR","system_prompt":"Você é um assistente. Seja conciso.","first_message":"Olá! Como posso ajudar?","sample_rate":8000})
+ same => n,Answer()
+ same => n,AudioSocket(${WS_URL},${CONFIG})
+ same => n,Hangup()
+```
+
+### Configuration JSON
+
+```json
+{
+  "provider": "aillomvox",
+  "voice": "Heitor",
+  "language": "pt-BR",
+  "system_prompt": "Você é um assistente virtual.",
+  "first_message": "Olá! Como posso ajudar?",
+  "farewell_message": "Obrigado por ligar. Até logo!",
+  "sample_rate": 8000,
+  "max_duration": 300
+}
+```
+
+**Note**: No `tools` array needed in Direct Mode.
+
+---
+
+## 🏗️ Architecture 2: Middleware Mode (Advanced)
+
+### When to Use
+- AI needs to **transfer** calls to extensions
+- AI needs to **hangup** via AMI (not just end conversation)
+- AI needs to **dial** external numbers
+- Advanced call control
+
+### Architecture
+```
+Asterisk → AudioSocket (port 9000) → Node.js Middleware
+                                            ↓
+                                       AMI/ARI Control
+                                            ↓
+                                     AillomVox Gateway
+```
+
+### Step 1: Install Dependencies
+
+```bash
+npm install aillom-vox-client asterisk-manager
+```
+
+### Step 2: Create Middleware (`asterisk-bridge.js`)
+
+```javascript
+const net = require('net');
+const AillomVoxClient = require('aillom-vox-client');
+const AMI = require('asterisk-manager');
+
+// AMI connection for Asterisk control
+const ami = new AMI(5038, 'localhost', 'admin', 'secret', true);
+
+ami.keepConnected();
+
+// AudioSocket server (receives from Asterisk)
+const server = net.createServer((socket) => {
+    console.log('[Bridge] New call from Asterisk');
+
+    // Connect to AillomVox
+    const client = new AillomVoxClient({
+        apiKey: process.env.AILLOM_API_KEY,
+        url: 'wss://vox.aillom.com/ws'
+    });
+
+    // Register client tools
+    client.connect({
+        provider: 'aillomvox',
+        voice: 'Heitor',
+        language: 'pt-BR',
+        system_prompt: 'Você é um assistente. Se o usuário pedir, transfira para ramal 100 ou desligue a ligação.',
+        sample_rate: 8000,
+        tools: [{
+            name: 'hangup',
+            description: 'End the call',
+            parameters: { type: 'object', properties: {} }
+        }, {
+            name: 'transfer',
+            description: 'Transfer call to extension',
+            parameters: {
+                type: 'object',
+                properties: {
+                    extension: { type: 'string', description: 'Target extension' }
+                },
+                required: ['extension']
+            }
+        }]
+    });
+
+    // Handle tool calls from AI
+    client.on('tool_call', async (tool) => {
+        console.log(`[Tool] AI called: ${tool.name}`, tool.args);
+        
+        if (tool.name === 'hangup') {
+            console.log('[Tool] Hanging up call');
+            socket.end();
+            client.disconnect();
+            return 'Call ended';
+        }
+        
+        if (tool.name === 'transfer') {
+            const ext = tool.args.extension;
+            console.log(`[Tool] Transferring to ${ext}`);
+            
+            // Use AMI to transfer (implement based on your channel tracking)
+            ami.action({
+                action: 'redirect',
+                channel: 'PJSIP/1234-00000001', // Track this from call setup
+                exten: ext,
+                context: 'from-internal',
+                priority: 1
+            });
+            
+            return `Transferred to extension ${ext}`;
+        }
+    });
+
+    // Pipe audio: Asterisk ↔ AillomVox
+    socket.on('data', (data) => {
+        // Parse AudioSocket protocol if needed, then send PCM
+        client.sendAudio(data);
+    });
+
+    client.on('audio', (pcmData) => {
+        socket.write(pcmData);
+    });
+
+    socket.on('end', () => {
+        console.log('[Bridge] Asterisk closed connection');
+        client.disconnect();
+    });
+});
+
+server.listen(9000, '127.0.0.1', () => {
+    console.log('[Bridge] Listening on 127.0.0.1:9000');
+});
+```
+
+### Step 3: Configure Asterisk
+
+```ini
+[from-internal]
+
+; Call extension 7000 using middleware (with client tools)
+exten => 7000,1,NoOp(AillomVox Middleware Mode)
+ same => n,Set(CONFIG={"provider":"aillomvox"})
+ same => n,Answer()
+ same => n,AudioSocket(127.0.0.1:9000,${CONFIG})
+ same => n,Hangup()
+```
+
+### Step 4: Run Middleware
+
+```bash
+AILLOM_API_KEY=your-api-key node asterisk-bridge.js
+```
+
+### Step 5: Test
+
+Call extension 7000 and say:
+- "Transfer me to extension 100" → AI calls `transfer` tool
+- "Goodbye" → AI calls `hangup` tool
+
+---
+
+## 🎙️ Audio Format
+
+### AudioSocket Protocol
+- **Format**: PCM 16-bit signed little-endian (`slin`)
+- **Sample Rate**: 8000 Hz (telephony standard)
+- **Channels**: 1 (mono)
+- **Encoding**: `pcm_s16le`
+
+### Codec Conversion (ulaw/alaw → slin)
+
+**No Brasil e na maioria dos países**, trunks SIP usam:
+- **ulaw** (G.711μ) - Padrão nos EUA/Brasil
+- **alaw** (G.711a) - Padrão na Europa
+
+**Asterisk converte automaticamente**:
+```
+Trunk SIP (ulaw/alaw) → Asterisk → slin → AudioSocket → AillomVox
+```
+
+Não precisa configurar nada! Asterisk faz a conversão transparente.
+
+### Forcing Codec (Optional)
+
+Se tiver problemas de áudio, force o codec:
+
+```ini
+exten => 6000,1,Set(CHANNEL(audioreadformat)=slin)
+ same => n,Set(CHANNEL(audiowriteformat)=slin)
+ same => n,Answer()
+ same => n,AudioSocket(...)
+```
+
+Isso garante que Asterisk sempre entrega PCM 16-bit para o AudioSocket.
+
+---
+
+## 🌍 Multi-Provider Examples (Direct Mode)
+
+### AillomVox (Best for Telephony)
+
+```ini
+exten => 7001,1,Set(CONFIG={"provider":"aillomvox","voice":"Heitor","sample_rate":8000})
+ same => n,AudioSocket(ws://vox.aillom.com/ws?apiKey=${AILLOM_API_KEY},${CONFIG})
+```
+
+**Why?** Lowest latency, optimized for 8kHz, $0.03/min.
+
+### Gemini 2.5 Flash
+
+```ini
+exten => 7002,1,Set(CONFIG={"provider":"gemini","voice":"Puck","sample_rate":8000})
+ same => n,AudioSocket(ws://vox.aillom.com/ws?apiKey=${AILLOM_API_KEY},${CONFIG})
+```
+
+**Why?** Multimodal, fast, $0.06/min.
+
+### OpenAI Realtime
+
+```ini
+exten => 7003,1,Set(CONFIG={"provider":"openai","voice":"shimmer","sample_rate":8000})
+ same => n,AudioSocket(ws://vox.aillom.com/ws?apiKey=${AILLOM_API_KEY},${CONFIG})
+```
+
+**Why?** Best for complex reasoning, $0.10/min.
+
+---
+
+## ⚠️ Troubleshooting
+
+### Problem: "Module audiosocket not loaded"
+
+```bash
+asterisk -rx "module load res_audiosocket"
+echo "load = res_audiosocket.so" >> /etc/asterisk/modules.conf
+```
+
+### Problem: "Connection refused"
+
+**Direct Mode**: Check firewall, verify server is running  
+**Middleware Mode**: Ensure middleware is running on `127.0.0.1:9000`
+
+```bash
+# Test direct connection
+curl -I https://vox.aillom.com/health
+
+# Test middleware
+netstat -tuln | grep 9000
+```
+
+### Problem: "No audio"
+
+Force codec:
+```ini
+exten => 6000,1,Set(CHANNEL(audioreadformat)=slin)
+ same => n,Set(CHANNEL(audiowriteformat)=slin)
+ same => n,AudioSocket(...)
+```
+
+---
+
+## 📊 Configuration Options
+
+| Field | Type | Description | Default |
+|-------|------|-------------|---------|
+| `provider` | string | `aillomvox`, `gemini`, `openai`, `qwen`, `grok`, `aws`, `ultravox` | **Required** |
+| `voice` | string | Voice ID (provider-specific) | **Required** |
+| `language` | string | `pt-BR`, `en-US`, `es-ES`, etc | `en-US` |
+| `system_prompt` | string | Instructions for AI | **Required** |
+| `first_message` | string | Initial greeting | `null` |
+| `farewell_message` | string | Goodbye message | `null` |
+| `sample_rate` | number | `8000` (tel), `16000` (hd) | **Required** |
+| `max_duration` | number | Max seconds (120-3600) | `300` |
+| `tools` | array | Client tools (Middleware only) | `[]` |
+
+---
+
+## 🌐 Production Checklist
+
+- [ ] AudioSocket module loaded and persistent
+- [ ] API key stored securely in `[globals]`
+- [ ] Sample rate set to 8000 Hz
+- [ ] Max duration configured
+- [ ] If using Middleware: process manager (PM2, systemd)
+- [ ] If using Middleware: AMI credentials configured
+- [ ] Tested with real calls
+- [ ] Monitoring enabled
+
+---
+
+## 💡 Which Architecture Should I Use?
+
+| Feature | Direct Mode | Middleware Mode |
+|---------|-------------|-----------------|
+| Simple conversations | ✅ Yes | ✅ Yes |
+| Transfer calls | ❌ No | ✅ Yes |
+| Hangup via AMI | ❌ No | ✅ Yes |
+| Dial external numbers | ❌ No | ✅ Yes |
+| Complexity | Low | Medium |
+| Setup | 2 minutes | 10 minutes |
+
+**Recommendation**: Start with **Direct Mode**. Upgrade to **Middleware** when you need client tools.
+
+---
+
+## 📚 Additional Resources
+
+- [Client Tools Guide](TOOLS.md)
+- [AillomVox Protocol](PROTOCOL.md)
+- [Provider Comparison](PROVIDERS.md)
+
+Happy building! 🎉

package/docs/PROTOCOL.md

@@ -0,0 +1,156 @@
+# WebSocket Protocol
+
+The AillomVox Gateway uses a WebSocket protocol for full-duplex audio streaming and control messaging.
+
+## Connection
+
+**Endpoint**: `wss://vox.aillom.com/ws`
+
+> **Note**: Authentication is performed in-band (inside the first message), not via HTTP headers or query params.
+
+## Message Flow
+
+```
+Client                              Server
+  |                                    |
+  |--- WebSocket Connect (GET /ws) --->|
+  |<--- 101 Switching Protocols -------|
+  |                                    |
+  |--- JSON Config (type: "config") -->|  ← MUST be first message
+  |                                    |  (Auth + Billing + Provider init)
+  |        ~500ms stabilization~       |
+  |                                    |
+  |--- Binary PCM Audio Chunks ------->|  ← 16-bit LE Mono
+  |<--- Binary PCM Audio Chunks -------|  ← AI response audio
+  |<--- JSON Events (transcript, etc) -|
+  |                                    |
+  |--- JSON { type: "hangup" } ------->|  ← or server-initiated
+  |<--- WebSocket Close ----------------|
+```
+
+## 1. Handshake (Client → Server)
+
+The **first message** must be a flat JSON config object. Sending binary data before this message results in connection termination (code `1008`).
+
+```json
+{
+  "type": "config",
+  "apikey": "av_your_api_key_here",
+  "provider": "aillomvox",
+  "voice": "Edward",
+  "language": "en-US",
+  "sample_rate": 16000,
+  "system_prompt": "You are a helpful assistant.",
+  "first_message": "Hello! How can I help you?",
+  "farewell_message": "Thank you for calling. Goodbye!",
+  "max_duration": 300,
+  "tools": [
+    {
+      "name": "hangup",
+      "description": "End the call when user says goodbye.",
+      "parameters": { "type": "object", "properties": {} }
+    }
+  ]
+}
+```
+
+| Field | Required | Type | Description |
+| :--- | :--- | :--- | :--- |
+| `type` | ✅ | string | Must be `"config"` |
+| `apikey` | ✅ | string | Your AillomVox API key |
+| `provider` | ✅ | string | `aillomvox`, `openai`, `gemini`, `aws`, `ultravox`, `grok`, `qwen` |
+| `sample_rate` | ✅ | number | `8000`, `16000`, or `24000` Hz |
+| `system_prompt` | ✅ | string | AI persona instructions |
+| `voice` | | string | Provider-specific voice ID |
+| `language` | | string | Locale code (e.g., `en-US`, `pt-BR`) |
+| `first_message` | | string | Greeting spoken on connect |
+| `farewell_message` | | string | Message before session close |
+| `max_duration` | | number | Session limit in seconds (60–3600) |
+| `tools` | | array | Client-side tool definitions |
+
+## 2. Audio (Binary Messages)
+
+After the handshake, audio flows as raw binary WebSocket messages in both directions.
+
+- **Format**: PCM 16-bit Signed Integer, Little Endian
+- **Channels**: Mono (1 channel)
+- **Rate**: Must match `sample_rate` from the handshake
+- **Direction**: Full duplex (bidirectional)
+
+> There is no JSON wrapper for audio. If the WebSocket message is binary, it is a raw audio chunk.
+
+## 3. Server → Client Events
+
+### Transcript
+```json
+{
+  "type": "transcript",
+  "role": "user",
+  "text": "Hello world",
+  "final": true
+}
+```
+- `role`: `"user"` or `"assistant"`
+- `final`: `true` when the sentence is complete. Only render `final: true` transcripts to avoid UI flickering.
+
+### Tool Call
+```json
+{
+  "type": "tool_call",
+  "call_id": "abc123",
+  "name": "hangup",
+  "args": {}
+}
+```
+Client must respond with a `tool_result` within 15 seconds (see below).
+
+### Playback Clear Buffer
+```json
+{
+  "type": "playback_clear_buffer"
+}
+```
+Sent when the user interrupts the AI. Client **must** immediately flush its audio playback queue.
+
+### Hangup
+```json
+{
+  "type": "hangup"
+}
+```
+Server-initiated session end. Client should stop audio, close socket, and reset UI.
+
+### Error
+```json
+{
+  "type": "error",
+  "message": "Invalid API Key"
+}
+```
+Error codes: `unauthorized`, `insufficient_balance`, `max_duration_reached`.
+
+## 4. Client → Server Events
+
+### Tool Result
+```json
+{
+  "type": "tool_result",
+  "call_id": "abc123",
+  "result": "Order status: shipped"
+}
+```
+**Mandatory** response after receiving a `tool_call`. The AI pauses execution until it receives this. Timeout: 15 seconds.
+
+### Hangup
+```json
+{
+  "type": "hangup"
+}
+```
+Client-initiated session end.
+
+## 5. Session Governance
+
+- **Max Duration**: 60–3600 seconds (default: 300)
+- **Farewell Warning**: At 15 seconds remaining, the AI speaks the `farewell_message`
+- **Force Close**: At 0 seconds, connection closes with `max_duration_reached`

package/docs/PROVIDERS.md

@@ -0,0 +1,40 @@
+# Supported AI Providers
+
+AillomVox aggregates top-tier Voice AI providers. Click on a provider to see detailed configuration and examples.
+
+## Provider Index
+
+| Provider | Model | Voices | Best For | Documentation |
+| :--- | :--- | :--- | :--- | :--- |
+| **AillomVox** | *Groq + Inworld TTS* | 65 voices | **Speed & Telephony**. Lowest latency, 8kHz native. | [Docs](providers/AILLOMVOX.md) |
+| **OpenAI** | `gpt-realtime-mini` | 6 voices | **Complex Logic**. Math, coding, strict reasoning. | [Docs](providers/OPENAI.md) |
+| **Gemini** | `gemini-2.5-flash` | 5 voices | **Long Context**. Massive memory, complex prompts. | [Docs](providers/GEMINI.md) |
+| **AWS** | `nova-2-sonic` | 3 voices | **Enterprise**. High reliability, AWS compliance. | [Docs](providers/AWS.md) |
+| **UltraVox** | `ultravox-v0.7` | 2 voices | **Emotion**. High emotional intelligence. | [Docs](providers/ULTRAVOX.md) |
+| **Grok** | `grok-beta` | Model-dependent | **Casual/Fun**. Witty, less robotic interactions. | [Docs](providers/GROK.md) |
+| **Qwen** | `qwen3-omni` | Model-dependent | **Cost & Asia**. High performance at lower cost. | [Docs](providers/QWEN.md) |
+
+See the complete [Voice Catalog](VOICES.md) for all voices across providers.
+
+## Quick Config Example
+
+```javascript
+// Connect to AillomVox
+ws.send(JSON.stringify({
+  type: "config",
+  apikey: "YOUR_API_KEY",
+  provider: "aillomvox",
+  voice: "Edward",
+  language: "en-US",
+  sample_rate: 16000,
+  system_prompt: "You are a helpful assistant."
+}));
+```
+
+---
+
+## ⚠️ Known Limitations
+
+| Provider | Limitation | Workaround |
+| :--- | :--- | :--- |
+| **Qwen** (`qwen3-omni-flash-realtime`) | **Function calling / Client Tools not supported** in WebSocket Realtime mode. The model will respond with text instead of emitting tool calls. | Use **AWS**, **OpenAI**, or **Gemini** for scenarios requiring tools (e.g., `hangup`, `transfer`). |