voiceblender 1.0.0__tar.gz

voiceblender-1.0.0/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//home/csiwek/go/src/voiceblender-workspace/**)",
+      "Bash(ls -la voiceblender-go/)"
+    ]
+  }
+}

voiceblender-1.0.0/.claude/settings.local.json

@@ -0,0 +1,14 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(make generate *)",
+      "Bash(python3 -c \"import sys; print\\(sys.prefix\\)\")",
+      "Bash(python3 -m pip list)",
+      "Bash(python3 -m pip show ruamel.yaml)",
+      "Bash(.venv/bin/python -c \"import ruamel.yaml, sys; print\\('ruamel OK in .venv:', ruamel.yaml.__version__ if hasattr\\(ruamel.yaml,'__version__'\\) else 'installed'\\); print\\(sys.executable\\)\")",
+      "Bash(.venv/bin/python -m pip list)",
+      "Bash(git checkout *)",
+      "Bash(PATH=__TRACKED_VAR__/.venv/bin:__TRACKED_VAR__ PY=.venv/bin/python make generate)"
+    ]
+  }
+}

voiceblender-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/

voiceblender-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Messageroute Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

voiceblender-1.0.0/Makefile

@@ -0,0 +1,40 @@
+# VOICEBLENDER points to the VoiceBlender repository root.
+# Override on the command line: make generate VOICEBLENDER=/other/path
+VOICEBLENDER ?= ../VoiceBlender
+OPENAPI      := $(VOICEBLENDER)/openapi.yaml
+ASYNCAPI     := $(VOICEBLENDER)/asyncapi.yaml
+
+PY ?= python3
+
+.PHONY: generate lint format typecheck test build install-dev clean
+
+# generate reads openapi.yaml + asyncapi.yaml and rewrites the generated files
+# (_models.py, _requests.py, _responses.py, _events.py, _legs.py, _rooms.py,
+# _webrtc.py, _vsi.py). Run this whenever either spec changes.
+generate:
+	$(PY) tools/generate.py --openapi $(OPENAPI) --asyncapi $(ASYNCAPI) --out src/voiceblender
+	ruff format src/voiceblender
+	ruff check --fix src/voiceblender
+	$(MAKE) typecheck
+
+lint:
+	ruff check src/voiceblender tools tests
+
+format:
+	ruff format src/voiceblender tools tests
+
+typecheck:
+	mypy src/voiceblender
+
+test:
+	pytest -q
+
+build:
+	$(PY) -m build
+
+install-dev:
+	$(PY) -m pip install -e ".[dev]"
+
+clean:
+	rm -rf build/ dist/ *.egg-info src/voiceblender/__pycache__ tests/__pycache__
+	rm -rf .mypy_cache .pytest_cache .ruff_cache

voiceblender-1.0.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: voiceblender
+Version: 1.0.0
+Summary: Python client for the VoiceBlender API
+Project-URL: Homepage, https://voiceblender.com
+Project-URL: Repository, https://github.com/VoiceBlender/voiceblender-python
+Author: Messageroute Ltd
+License: MIT License
+        
+        Copyright (c) 2026 Messageroute Ltd
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: sip,telephony,voice,voiceblender,webrtc
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Telephony
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: websockets>=13
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruamel-yaml>=0.18; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# voiceblender-python
+
+> [!IMPORTANT]
+> **This library is auto-generated.** Models, request/response/event types, and
+> method bindings are produced by `tools/generate.py` from the OpenAPI/AsyncAPI
+> specs (see [Code generation](#code-generation)). Do **not** edit the generated
+> sources directly — your changes will be overwritten on the next run. Open pull
+> requests against the generator (`tools/generate.py`) and/or the upstream specs
+> only.
+
+Python client for the [VoiceBlender](https://voiceblender.com) API.
+
+VoiceBlender bridges SIP and WebRTC voice calls with multi-party audio mixing,
+real-time speech-to-text, text-to-speech, AI agent integration, recording, and
+webhook-based event delivery.
+
+This is a Python port of [voiceblender-go](https://github.com/VoiceBlender/voiceblender-go).
+Models, request types, response types, event types, and method bindings are
+**code-generated** from `../VoiceBlender/openapi.yaml` + `asyncapi.yaml` by
+`tools/generate.py` — the same spec-driven pattern as the Go SDK.
+
+## Installation
+
+```bash
+pip install voiceblender
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+import voiceblender
+
+async def main():
+    async with voiceblender.Client(base_url="http://localhost:8080/v1") as c:
+        leg = await c.create_leg(voiceblender.CreateLegRequest(
+            type=voiceblender.LegType.SIP_OUTBOUND,
+            to="sip:alice@example.com",
+        ))
+        print("Created leg:", leg.id)
+
+asyncio.run(main())
+```
+
+## Quick start (sync)
+
+```python
+from voiceblender.sync import SyncClient
+import voiceblender
+
+with SyncClient(base_url="http://localhost:8080/v1") as c:
+    leg = c.create_leg(voiceblender.CreateLegRequest(
+        type=voiceblender.LegType.SIP_OUTBOUND,
+        to="sip:alice@example.com",
+    ))
+    print("Created leg:", leg.id)
+```
+
+## Code generation
+
+```bash
+make generate   # regenerate from openapi.yaml + asyncapi.yaml
+make test       # run pytest
+make lint       # ruff check
+make typecheck  # mypy --strict
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

voiceblender-1.0.0/README.md

@@ -0,0 +1,70 @@
+# voiceblender-python
+
+> [!IMPORTANT]
+> **This library is auto-generated.** Models, request/response/event types, and
+> method bindings are produced by `tools/generate.py` from the OpenAPI/AsyncAPI
+> specs (see [Code generation](#code-generation)). Do **not** edit the generated
+> sources directly — your changes will be overwritten on the next run. Open pull
+> requests against the generator (`tools/generate.py`) and/or the upstream specs
+> only.
+
+Python client for the [VoiceBlender](https://voiceblender.com) API.
+
+VoiceBlender bridges SIP and WebRTC voice calls with multi-party audio mixing,
+real-time speech-to-text, text-to-speech, AI agent integration, recording, and
+webhook-based event delivery.
+
+This is a Python port of [voiceblender-go](https://github.com/VoiceBlender/voiceblender-go).
+Models, request types, response types, event types, and method bindings are
+**code-generated** from `../VoiceBlender/openapi.yaml` + `asyncapi.yaml` by
+`tools/generate.py` — the same spec-driven pattern as the Go SDK.
+
+## Installation
+
+```bash
+pip install voiceblender
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+import voiceblender
+
+async def main():
+    async with voiceblender.Client(base_url="http://localhost:8080/v1") as c:
+        leg = await c.create_leg(voiceblender.CreateLegRequest(
+            type=voiceblender.LegType.SIP_OUTBOUND,
+            to="sip:alice@example.com",
+        ))
+        print("Created leg:", leg.id)
+
+asyncio.run(main())
+```
+
+## Quick start (sync)
+
+```python
+from voiceblender.sync import SyncClient
+import voiceblender
+
+with SyncClient(base_url="http://localhost:8080/v1") as c:
+    leg = c.create_leg(voiceblender.CreateLegRequest(
+        type=voiceblender.LegType.SIP_OUTBOUND,
+        to="sip:alice@example.com",
+    ))
+    print("Created leg:", leg.id)
+```
+
+## Code generation
+
+```bash
+make generate   # regenerate from openapi.yaml + asyncapi.yaml
+make test       # run pytest
+make lint       # ruff check
+make typecheck  # mypy --strict
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

voiceblender-1.0.0/examples/ivr/.env.example

@@ -0,0 +1,21 @@
+# VoiceBlender IVR — example environment variables
+# Copy to .env and fill in the required values.
+
+# VoiceBlender API base URL. The IVR connects to <VOICEBLENDER_URL>/vsi
+# (with http:// → ws:// and https:// → wss:// substitution) over a single
+# outbound WebSocket — no inbound port to open.
+VOICEBLENDER_URL=http://localhost:8080/v1
+
+# TTS API key (e.g. ElevenLabs).
+# Optional if already configured in the VoiceBlender service.
+# TTS_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Deepgram API key for the AI agent (operator queue, digit 0).
+# DEEPGRAM_API_KEY=
+
+# TTS voice / provider used for all IVR prompts.
+TTS_VOICE=Rachel
+TTS_PROVIDER=elevenlabs
+
+# Company name spoken in the greeting.
+COMPANY_NAME=Acme Corp

voiceblender-1.0.0/examples/ivr/README.md

@@ -0,0 +1,118 @@
+# Example: Company IVR (VSI / Python)
+
+A multi-department IVR (Interactive Voice Response) that answers inbound calls,
+greets the caller with a TTS prompt, presents a DTMF menu, and routes the
+caller to a department room — wired up over a **single outbound WebSocket** to
+VoiceBlender's `/v1/vsi` endpoint.
+
+This is a VSI redesign of [`../../../voiceblender-go/examples/ivr`](../../../voiceblender-go/examples/ivr),
+which uses REST + HTTP webhooks. The behaviour is identical; the I/O substrate
+is different.
+
+## Call flow
+
+```
+Inbound call
+  └─ leg.ringing      → early media: UK ringback for 3 s → answer
+  └─ leg.connected    → "Thank you for calling Acme Corp. Please hold…"
+  └─ tts.finished     → main menu prompt
+  └─ dtmf.received
+       1 → Sales queue
+       2 → Support queue
+       3 → Billing queue
+       0 → Operator queue (Deepgram AI agent)
+       9 → Repeat menu
+       * → Goodbye → hang up
+       ? → "Invalid option, please try again" (max 3 attempts, then goodbye)
+  └─ leg.disconnected → cleanup
+```
+
+Once a caller is routed, they are added to the department's persistent room
+where agents can join to handle the call. Hold music is played in the room
+while they wait.
+
+## Architecture
+
+```
+SIP carrier
+    │  inbound INVITE
+    ▼
+VoiceBlender                      ◄──── outbound WS ◄────  IVR (this program)
+    │  events (leg.ringing, dtmf.received, tts.finished, …)
+    │
+    ▼                             ──── VSI command frames ──►
+(same WebSocket, bidirectional)
+
+                                  ◄──── <cmd>.result ────
+```
+
+No inbound HTTP server. No public DNS. No ngrok. The IVR is a plain WebSocket
+client — deployable behind any firewall that allows outbound connections to
+VoiceBlender.
+
+## Prerequisites
+
+- A running [VoiceBlender](https://github.com/VoiceBlender/voiceblender) instance
+  reachable on the network from this host
+- An [ElevenLabs](https://elevenlabs.io) API key for TTS prompts, unless already
+  configured in VoiceBlender
+- Python 3.10+
+
+## Configuration
+
+| Environment variable | Required | Default | Description |
+|----------------------|----------|---------|-------------|
+| `VOICEBLENDER_URL`   | no       | `http://localhost:8080/v1` | VoiceBlender API base URL |
+| `TTS_API_KEY`        | no       | — | TTS API key (omit if pre-configured in VoiceBlender) |
+| `TTS_VOICE`          | no       | `Rachel` | TTS voice name |
+| `TTS_PROVIDER`       | no       | `elevenlabs` | TTS provider name |
+| `DEEPGRAM_API_KEY`   | no       | — | Deepgram API key for the operator AI agent |
+| `COMPANY_NAME`       | no       | `Acme Corp` | Company name spoken in greeting |
+
+See [`.env.example`](.env.example) for a copy-paste-ready template.
+
+## Running
+
+From the `voiceblender-python` repo root:
+
+```bash
+pip install -e ".[dev]"            # one-time
+python examples/ivr/main.py
+```
+
+That's it. No port to forward, no tunnel to set up.
+
+VoiceBlender must be configured to send inbound SIP calls to the same
+instance. The IVR creates the four department rooms (`sales`, `support`,
+`billing`, `operator`) on startup if they don't already exist — using the VSI
+`create_room` command, no webhook registration required.
+
+## Code structure
+
+Each active call is a `Call` dataclass holding the current IVR state
+(`GREETING → MENU → ROUTED/GOODBYE`). Events arrive over the WebSocket and
+are dispatched to `asyncio.create_task` handlers so the read loop never
+blocks; all state transitions are protected by a per-call `asyncio.Lock`.
+
+| Old (REST + webhook) | New (VSI) |
+|----------------------|-----------|
+| `aiohttp.web.Application` + `/webhook` route | `client.events_stream()` + `client.subscribe()` |
+| `voiceblender.Client._do(...)` (HTTP) | `stream.<vsi_method>(...)` (WS) |
+| `leg.early_media(...)` / `leg.play(...)` / … | `stream.leg_early_media(payload)` / `stream.leg_play_start(payload)` / … |
+| `room.add_leg(...)` / `room.play(...)` | `stream.add_leg_to_room(payload)` / `stream.room_play_start(payload)` |
+| `client.create_room(...)` | `stream.create_room(CreateRoomRequest(...))` |
+
+The TTS sequencing trick is identical: each call tracks its `active_tts_id`
+and `tts.finished` events for replaced prompts are silently discarded.
+
+## Reconnect
+
+`main.py` wraps the stream loop in a simple `while True: try / except +
+asyncio.sleep(5)` block. On any disconnect (network blip, server restart) the
+IVR drops its in-memory call state and reconnects after a fixed 5-second
+delay. In-flight calls that survive the disconnect would have to re-ring; that
+matches what the server already does on its side.
+
+A production deployment should swap the fixed delay for exponential backoff
+and may want to reconcile per-call state across reconnects via `list_legs` /
+`list_rooms` VSI commands.