pipecat-vobiz 0.0.1__tar.gz

pipecat_vobiz-0.0.1/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.0.1] - 2025-01-23
+
+### Added
+
+- Initial release of `pipecat-vobiz`
+- `VobizFrameSerializer` implementation
+- Support for 8kHz μ-law audio streaming
+- Support for DTMF events
+- Automatic call hangup on pipeline end

pipecat_vobiz-0.0.1/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2024, Piyush Sahoo
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pipecat_vobiz-0.0.1/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: pipecat-vobiz
+Version: 0.0.1
+Summary: Vobiz telephony integration for Pipecat
+Project-URL: Homepage, https://github.com/Piyush-sahoo/Pipecat-Vobiz
+Project-URL: Repository, https://github.com/Piyush-sahoo/Pipecat-Vobiz
+Author: Piyush Sahoo
+License: BSD-2-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: pipecat-ai>=0.0.80
+Description-Content-Type: text/markdown
+
+# Pipecat Vobiz Integration
+
+Community integration for using [Vobiz](https://vobiz.ai) telephony with [Pipecat](https://github.com/pipecat-ai/pipecat).
+
+## Installation
+
+```bash
+pip install pipecat-vobiz
+```
+
+Or install from source:
+
+```bash
+pip install git+https://github.com/Piyush-sahoo/Pipecat-Vobiz.git
+```
+
+## Usage
+
+```python
+from pipecat.serializers.vobiz import VobizFrameSerializer
+from pipecat.transports.network.fastapi_websocket import (
+    FastAPIWebsocketTransport,
+    FastAPIWebsocketParams,
+)
+
+# Create the serializer with your Vobiz credentials
+serializer = VobizFrameSerializer(
+    stream_id=stream_id,
+    call_id=call_id,
+    auth_id="YOUR_VOBIZ_AUTH_ID",
+    auth_token="YOUR_VOBIZ_AUTH_TOKEN",
+)
+
+# Use it with the FastAPI WebSocket transport
+transport = FastAPIWebsocketTransport(
+    websocket=websocket,
+    params=FastAPIWebsocketParams(
+        audio_in_enabled=True,
+        audio_out_enabled=True,
+        add_wav_header=False,
+        serializer=serializer,
+    ),
+)
+```
+
+## Features
+
+- 8kHz μ-law audio streaming
+- DTMF event handling
+- Automatic call termination on pipeline end
+- Compatible with Pipecat's pipeline architecture
+
+## Example
+
+See the [examples/bot.py](examples/bot.py) for a complete working example.
+
+## Pipecat Version Compatibility
+
+Tested with Pipecat v0.0.86+
+
+## License
+
+BSD 2-Clause License

pipecat_vobiz-0.0.1/README.md

@@ -0,0 +1,63 @@
+# Pipecat Vobiz Integration
+
+Community integration for using [Vobiz](https://vobiz.ai) telephony with [Pipecat](https://github.com/pipecat-ai/pipecat).
+
+## Installation
+
+```bash
+pip install pipecat-vobiz
+```
+
+Or install from source:
+
+```bash
+pip install git+https://github.com/Piyush-sahoo/Pipecat-Vobiz.git
+```
+
+## Usage
+
+```python
+from pipecat.serializers.vobiz import VobizFrameSerializer
+from pipecat.transports.network.fastapi_websocket import (
+    FastAPIWebsocketTransport,
+    FastAPIWebsocketParams,
+)
+
+# Create the serializer with your Vobiz credentials
+serializer = VobizFrameSerializer(
+    stream_id=stream_id,
+    call_id=call_id,
+    auth_id="YOUR_VOBIZ_AUTH_ID",
+    auth_token="YOUR_VOBIZ_AUTH_TOKEN",
+)
+
+# Use it with the FastAPI WebSocket transport
+transport = FastAPIWebsocketTransport(
+    websocket=websocket,
+    params=FastAPIWebsocketParams(
+        audio_in_enabled=True,
+        audio_out_enabled=True,
+        add_wav_header=False,
+        serializer=serializer,
+    ),
+)
+```
+
+## Features
+
+- 8kHz μ-law audio streaming
+- DTMF event handling
+- Automatic call termination on pipeline end
+- Compatible with Pipecat's pipeline architecture
+
+## Example
+
+See the [examples/bot.py](examples/bot.py) for a complete working example.
+
+## Pipecat Version Compatibility
+
+Tested with Pipecat v0.0.86+
+
+## License
+
+BSD 2-Clause License

pipecat_vobiz-0.0.1/examples/README.md

@@ -0,0 +1,359 @@
+# Vobiz + Pipecat AI Voice Agent
+
+AI-powered outbound calling system built with [Vobiz](https://vobiz.ai) telephony API and [Pipecat](https://pipecat.ai) voice agent framework.
+
+## Features
+
+- 🤖 **AI Voice Conversations** - Natural conversations powered by OpenAI GPT + TTS/STT
+- 📞 **Outbound Calling** - Trigger calls via REST API from anywhere
+- 🎙️ **Automatic Recording** - All conversations automatically recorded and saved
+- 🔄 **Real-time Streaming** - Bidirectional audio via WebSockets
+- 🚀 **Simple Setup** - Just Python, no Docker required
+
+## How It Works
+
+```
+curl POST → Vobiz API → Call initiated → Call answered →
+Vobiz requests XML → Server returns WebSocket URL →
+Audio streams → Pipecat bot (STT → LLM → TTS) →
+AI conversation + Recording saved
+```
+
+## Prerequisites
+
+1. **Vobiz Account**
+   - Sign up at [vobiz.ai](https://vobiz.ai)
+   - Get your Auth ID and Auth Token
+   - (Optional) Purchase a phone number for the `/start` endpoint
+
+2. **OpenAI API Key**
+   - Sign up at [platform.openai.com](https://platform.openai.com)
+   - Create an API key with credits
+
+3. **ngrok** (for local development)
+   - Sign up at [ngrok.com](https://ngrok.com)
+   - Download and install ngrok
+
+4. **Python 3.10+**
+
+## Installation
+
+1. **Clone the repository**
+```bash
+git clone <your-repo-url>
+cd outbound
+```
+
+2. **Install dependencies**
+```bash
+pip install -r requirements.txt
+```
+
+3. **Configure environment**
+```bash
+cp env.example .env
+```
+
+Edit `.env` and add your credentials:
+```env
+OPENAI_API_KEY=sk-...
+VOBIZ_AUTH_ID=MA_XXXXXXXX
+VOBIZ_AUTH_TOKEN=your-token-here
+PUBLIC_URL=https://your-ngrok-url.ngrok-free.app
+```
+
+## Usage
+
+### 1. Start the Server
+
+```bash
+python server.py
+```
+
+Server runs on `http://0.0.0.0:7860`
+
+### 2. Start ngrok (for local testing)
+
+In a new terminal:
+```bash
+ngrok http 7860
+```
+
+Copy the ngrok URL (e.g., `https://abc123.ngrok-free.app`) and update `PUBLIC_URL` in `.env`
+
+**Restart the server** to load the new PUBLIC_URL.
+
+### 3. Make a Call
+
+Call Vobiz API directly from anywhere:
+
+```bash
+curl -X POST https://api.vobiz.ai/api/v1/Account/YOUR_AUTH_ID/Call/ \
+  -H "X-Auth-ID: YOUR_AUTH_ID" \
+  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from": "+918011223344",
+    "to": "+919148112233",
+    "answer_url": "https://your-ngrok-url.ngrok-free.app/answer",
+    "answer_method": "POST"
+  }'
+```
+
+Replace:
+- `YOUR_AUTH_ID` - Your Vobiz Auth ID
+- `YOUR_AUTH_TOKEN` - Your Vobiz Auth Token
+- `+918011223344` - Caller ID (from number)
+- `+919148112233` - Number to call (to number)
+- `your-ngrok-url.ngrok-free.app` - Your ngrok URL
+
+### 4. Have a Conversation
+
+1. Phone rings at the "to" number
+2. Answer the call
+3. Bot speaks and listens
+4. Have a natural AI-powered conversation
+5. Conversation is automatically recorded
+
+## Accessing Recordings
+
+Recordings are automatically downloaded to the `recordings/` folder as MP3 files.
+
+You'll see in server logs:
+```
+[RECORDING CALLBACK] ✅ Downloaded to recordings/{recording-id}.mp3
+[RECORDING CALLBACK] File size: 123456 bytes
+```
+
+### Manual Download
+
+If auto-download fails, use curl with authentication:
+
+```bash
+curl -X GET "https://media.vobiz.ai/v1/Account/YOUR_AUTH_ID/Recording/{recording-id}.mp3" \
+  -H "X-Auth-ID: YOUR_AUTH_ID" \
+  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
+  -o recording.mp3
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | ✅ Yes | OpenAI API key for LLM, STT, TTS |
+| `VOBIZ_AUTH_ID` | ✅ Yes | Your Vobiz Auth ID |
+| `VOBIZ_AUTH_TOKEN` | ✅ Yes | Your Vobiz Auth Token |
+| `PUBLIC_URL` | ✅ Yes | Your ngrok URL (for local dev) |
+| `VOBIZ_PHONE_NUMBER` | ❌ No | Optional, only for `/start` endpoint |
+| `DEEPGRAM_API_KEY` | ❌ No | Optional, alternative STT provider |
+
+### Customizing the Bot
+
+Edit `bot.py` to customize the AI assistant:
+
+**Change the bot's personality:**
+```python
+messages = [
+    {
+        "role": "system",
+        "content": "You are a friendly customer service agent..."
+    },
+]
+```
+
+**Change TTS voice:**
+```python
+tts = OpenAITTSService(
+    api_key=os.getenv("OPENAI_API_KEY"),
+    voice="nova",  # Options: alloy, echo, fable, onyx, nova, shimmer
+)
+```
+
+**Use different LLM:**
+```python
+llm = OpenAILLMService(
+    api_key=os.getenv("OPENAI_API_KEY"),
+    model="gpt-4-turbo"  # or "gpt-3.5-turbo" for cheaper
+)
+```
+
+## API Endpoints
+
+### `POST /start`
+Initiate a call via your server (alternative to direct Vobiz API)
+
+**Request:**
+```json
+{
+  "phone_number": "+919148112233",
+  "from_number": "+918011223344"  // optional
+}
+```
+
+### `POST /answer`
+Called by Vobiz when call is answered. Returns XML with WebSocket URL.
+
+### `/ws`
+WebSocket endpoint for bidirectional audio streaming.
+
+### `POST /recording-finished`
+Called by Vobiz when recording stops. Logs recording details.
+
+### `POST /recording-ready`
+Called by Vobiz when recording file is ready. Auto-downloads the MP3.
+
+## Architecture
+
+### Components
+
+1. **server.py** - FastAPI server handling HTTP/WebSocket
+2. **bot.py** - Pipecat voice agent (STT → LLM → TTS pipeline)
+3. **Vobiz API** - Telephony service (call initiation, audio routing)
+4. **ngrok** - Public URL tunnel (for local development)
+
+### Call Flow
+
+```
+┌─────────────┐
+│  You (curl) │
+└──────┬──────┘
+       │
+       ↓ POST /Call/
+┌─────────────────┐
+│  Vobiz API      │
+└──────┬──────────┘
+       │
+       ↓ Call initiated
+┌─────────────────┐
+│  Phone rings    │
+└──────┬──────────┘
+       │
+       ↓ Call answered
+┌─────────────────┐
+│  Vobiz → POST   │
+│  /answer        │
+└──────┬──────────┘
+       │
+       ↓ Returns XML
+┌─────────────────┐
+│  <Stream>       │
+│  wss://...      │
+│  </Stream>      │
+└──────┬──────────┘
+       │
+       ↓ WebSocket connect
+┌─────────────────┐
+│  Pipecat Bot    │
+│  STT → LLM → TTS│
+└──────┬──────────┘
+       │
+       ↓
+┌─────────────────┐
+│  AI Conversation│
+│  + Recording    │
+└─────────────────┘
+```
+
+## Troubleshooting
+
+### Call Doesn't Connect
+
+**Check:**
+- Is `server.py` running?
+- Is ngrok running?
+- Does `answer_url` match your ngrok URL?
+- Is phone number in E.164 format? (`+14155555678`)
+
+**Test manually:**
+```bash
+curl https://your-ngrok-url.ngrok-free.app/answer
+```
+Should return XML.
+
+### Bot Doesn't Speak
+
+**Check:**
+- Server logs show WebSocket connection?
+- `PUBLIC_URL` set in `.env`?
+- Restart server after changing `PUBLIC_URL`
+
+### Can't Access Recordings
+
+Vobiz recording URLs require authentication. Use curl with headers:
+
+```bash
+curl -X GET "https://media.vobiz.ai/..." \
+  -H "X-Auth-ID: YOUR_AUTH_ID" \
+  -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
+  -o recording.mp3
+```
+
+Or check `recordings/` folder for auto-downloaded files.
+
+### ngrok URL Changes
+
+Free ngrok URLs change on restart. When this happens:
+
+1. Update `PUBLIC_URL` in `.env`
+2. Restart `server.py`
+3. Update `answer_url` in curl commands
+
+**Solution:** Use ngrok paid plan for permanent URL.
+
+## Vobiz XML Elements
+
+The server returns XML that controls call behavior:
+
+### Speak - Play TTS message
+```xml
+<Speak voice="WOMAN" language="en-US">
+    Hello! Welcome to our service.
+</Speak>
+```
+
+### Stream - Connect to WebSocket
+```xml
+<Stream bidirectional="true" contentType="audio/x-mulaw;rate=8000">
+    wss://your-server.com/ws
+</Stream>
+```
+
+### Record - Record the call
+```xml
+<Record
+    action="https://your-server.com/recording-finished"
+    recordSession="true"
+    maxLength="3600"
+    fileFormat="mp3"
+/>
+```
+
+## Production Deployment
+
+For production, deploy to a cloud provider instead of ngrok:
+
+1. **Deploy server.py** to AWS/GCP/Heroku/etc.
+2. **Get a domain** (e.g., `api.yourcompany.com`)
+3. **Set PUBLIC_URL** to your domain
+4. **Use HTTPS** (Let's Encrypt, Cloudflare, etc.)
+5. **Make calls** using your production domain
+
+## Resources
+
+- [Vobiz Documentation](https://docs.vobiz.ai)
+- [Pipecat Documentation](https://docs.pipecat.ai)
+- [OpenAI API Documentation](https://platform.openai.com/docs)
+- [ngrok Documentation](https://ngrok.com/docs)
+
+## Support
+
+For issues related to:
+- **Vobiz API** - Contact Vobiz support
+- **Pipecat** - Check Pipecat documentation/Discord
+- **This integration** - Open an issue on GitHub
+
+---
+
+**Built with ❤️ using Vobiz + Pipecat**

pipecat_vobiz-0.0.1/examples/bot.py

@@ -0,0 +1,126 @@
+#
+# Copyright (c) 2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+import os
+
+from dotenv import load_dotenv
+from loguru import logger
+from pipecat.audio.vad.silero import SileroVADAnalyzer
+from pipecat.pipeline.pipeline import Pipeline
+from pipecat.pipeline.runner import PipelineRunner
+from pipecat.pipeline.task import PipelineParams, PipelineTask
+from pipecat.processors.aggregators.llm_context import LLMContext
+from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
+from pipecat.runner.types import RunnerArguments
+from pipecat.runner.utils import parse_telephony_websocket
+from pipecat.serializers.vobiz import VobizFrameSerializer
+from pipecat.services.openai.llm import OpenAILLMService
+from pipecat.services.openai.stt import OpenAISTTService
+from pipecat.services.openai.tts import OpenAITTSService
+from pipecat.transports.base_transport import BaseTransport
+from pipecat.transports.websocket.fastapi import (
+    FastAPIWebsocketParams,
+    FastAPIWebsocketTransport,
+)
+
+load_dotenv(override=True)
+
+
+async def run_bot(transport: BaseTransport, handle_sigint: bool):
+    llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))
+
+    stt = OpenAISTTService(api_key=os.getenv("OPENAI_API_KEY"))
+
+    tts = OpenAITTSService(
+        api_key=os.getenv("OPENAI_API_KEY"),
+        voice="ballad",
+    )
+
+    messages = [
+        {
+            "role": "system",
+            "content": (
+                "You are a friendly assistant. "
+                "Your responses will be read aloud, so keep them concise and conversational. "
+                "Avoid special characters or formatting. "
+                "Begin by saying: 'Hello! This is an automated call from our Vobiz AI assistant.'"
+            ),
+        },
+    ]
+
+    context = LLMContext(messages)
+    context_aggregator = LLMContextAggregatorPair(context)
+
+    pipeline = Pipeline(
+        [
+            transport.input(),  # Websocket input from client
+            stt,  # Speech-To-Text
+            context_aggregator.user(),
+            llm,  # LLM
+            tts,  # Text-To-Speech
+            transport.output(),  # Websocket output to client
+            context_aggregator.assistant(),
+        ]
+    )
+
+    task = PipelineTask(
+        pipeline,
+        params=PipelineParams(
+            audio_in_sample_rate=8000,   # Vobiz MULAW input (8kHz telephony)
+            audio_out_sample_rate=24000, # OpenAI TTS native (auto-resampled to 8kHz for Vobiz)
+            enable_metrics=True,
+            enable_usage_metrics=True,
+        ),
+    )
+
+    @transport.event_handler("on_client_connected")
+    async def on_client_connected(transport, client):
+        # Wait for the user to speak first 
+        logger.info("Starting outbound call conversation")
+
+    @transport.event_handler("on_client_disconnected")
+    async def on_client_disconnected(transport, client):
+        logger.info("Outbound call ended")
+        await task.cancel()
+
+    runner = PipelineRunner(handle_sigint=handle_sigint)
+
+    await runner.run(task)
+
+
+async def bot(runner_args: RunnerArguments):
+    """Main bot entry point compatible with Pipecat Cloud."""
+
+    # Parse the telephony WebSocket to extract stream_id and call_id
+    transport_type, call_data = await parse_telephony_websocket(runner_args.websocket)
+    logger.info(f"Transport type: {transport_type}, Call data: {call_data}")
+
+    serializer = VobizFrameSerializer(
+        stream_id=call_data.get("stream_id", ""),
+        call_id=call_data.get("call_id", ""),
+        auth_id=os.getenv("VOBIZ_AUTH_ID", ""),
+        auth_token=os.getenv("VOBIZ_AUTH_TOKEN", ""),
+        params=VobizFrameSerializer.InputParams(
+            vobiz_sample_rate=8000,  
+            sample_rate=None,  # Uses pipeline default
+            auto_hang_up=True  # Automatically hangs up on EndFrame
+        )
+    )
+
+    transport = FastAPIWebsocketTransport(
+        websocket=runner_args.websocket,
+        params=FastAPIWebsocketParams(
+            audio_in_enabled=True,
+            audio_out_enabled=True,
+            add_wav_header=False,  # CRITICAL: Must be False for telephony
+            serializer=serializer,  # (Vobiz is Plivo-compatible)
+            vad_analyzer=SileroVADAnalyzer(),
+        ),
+    )
+
+    handle_sigint = runner_args.handle_sigint
+
+    await run_bot(transport, handle_sigint)

pipecat_vobiz-0.0.1/examples/env.example

@@ -0,0 +1,22 @@
+# OpenAI API Key (Required for LLM, STT, TTS)
+OPENAI_API_KEY=
+
+# Deepgram API Key (Optional - alternative STT provider)
+DEEPGRAM_API_KEY=
+
+# Vobiz Credentials (Required)
+VOBIZ_AUTH_ID=
+VOBIZ_AUTH_TOKEN=
+
+# Vobiz Phone Number (Optional)
+# Only required if using /start endpoint
+# Not needed if calling Vobiz API directly with curl
+VOBIZ_PHONE_NUMBER=
+
+# Environment configuration
+ENV=local
+
+# Public URL (Required for ngrok deployments)
+# Update this with your ngrok URL when testing locally
+# Example: PUBLIC_URL=https://abc123.ngrok-free.app
+PUBLIC_URL=

pipecat_vobiz-0.0.1/examples/requirements.txt

@@ -0,0 +1,15 @@
+# Pipecat AI with required features
+pipecat-ai[websocket,openai,silero]>=0.0.86
+
+# Web framework
+fastapi
+uvicorn
+
+# HTTP client
+aiohttp
+
+# Environment variables
+python-dotenv
+
+# Logging
+loguru