jambonz-python-sdk 0.2.0__py3-none-any.whl

jambonz_sdk/verb_registry.py

@@ -0,0 +1,102 @@
+"""Verb registry — the single source of truth for mapping spec entries to SDK methods.
+
+This module defines which entries in ``specs.json`` are top-level verbs
+(as opposed to nested component types), their Python method names, docstrings,
+and any synonym/alias transforms.
+
+When the spec adds a new verb, add one entry here — the VerbBuilder will
+automatically gain a typed method for it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class VerbDef:
+    """Definition of a single verb method on VerbBuilder.
+
+    Attributes:
+        spec_name: The key in specs.json (e.g., ``"say"``, ``"sip:decline"``).
+        method_name: The Python method name (e.g., ``"say"``, ``"sip_decline"``).
+        json_verb: The ``verb`` value in the output JSON. Defaults to ``spec_name``.
+        doc: One-line docstring for the generated method.
+        inject: Properties to inject into the verb data (for synonyms like
+            ``openai_s2s`` → ``llm`` with ``vendor: "openai"``).
+    """
+
+    spec_name: str
+    method_name: str
+    json_verb: str = ""
+    doc: str = ""
+    inject: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.json_verb:
+            object.__setattr__(self, "json_verb", self.spec_name)
+
+
+# ── Verb definitions ────────────────────────────────────────────────
+# Each entry here creates a method on VerbBuilder.
+# Order matches the categories in the jambonz documentation.
+
+VERB_DEFS: list[VerbDef] = [
+    # Audio & Speech
+    VerbDef("say", "say", doc="Speak text using TTS."),
+    VerbDef("play", "play", doc="Play an audio file from a URL."),
+    VerbDef("gather", "gather", doc="Collect speech (STT) and/or DTMF input."),
+
+    # AI & Real-time
+    VerbDef("llm", "openai_s2s", json_verb="openai_s2s",
+            doc="Connect caller to OpenAI for real-time voice conversation.",
+            inject={"vendor": "openai"}),
+    VerbDef("llm", "google_s2s", json_verb="google_s2s",
+            doc="Connect caller to Google for real-time voice conversation.",
+            inject={"vendor": "google"}),
+    VerbDef("llm", "deepgram_s2s", json_verb="deepgram_s2s",
+            doc="Connect caller to Deepgram for real-time voice conversation.",
+            inject={"vendor": "deepgram"}),
+    VerbDef("llm", "elevenlabs_s2s", json_verb="elevenlabs_s2s",
+            doc="Connect caller to ElevenLabs Conversational AI agent.",
+            inject={"vendor": "elevenlabs"}),
+    VerbDef("llm", "ultravox_s2s", json_verb="ultravox_s2s",
+            doc="Connect caller to Ultravox for real-time voice conversation.",
+            inject={"vendor": "ultravox"}),
+    VerbDef("llm", "s2s", json_verb="s2s",
+            doc="Generic S2S verb (use when vendor is determined at runtime)."),
+    VerbDef("llm", "llm", doc="Legacy LLM verb (prefer s2s or vendor-specific shortcuts)."),
+    VerbDef("dialogflow", "dialogflow", doc="Connect caller to Google Dialogflow agent."),
+    VerbDef("pipeline", "pipeline", doc="Integrated STT → LLM → TTS voice AI pipeline."),
+
+    # Audio Streaming
+    VerbDef("listen", "listen", doc="Stream real-time audio to a websocket endpoint."),
+    VerbDef("listen", "stream", json_verb="stream",
+            doc="Stream real-time audio (preferred alias for listen)."),
+    VerbDef("transcribe", "transcribe", doc="Enable real-time call transcription."),
+
+    # Call Control
+    VerbDef("dial", "dial", doc="Place outbound call and bridge to current caller."),
+    VerbDef("conference", "conference", doc="Place caller into a multi-party conference room."),
+    VerbDef("enqueue", "enqueue", doc="Place caller into a named call queue."),
+    VerbDef("dequeue", "dequeue", doc="Remove caller from a queue and bridge."),
+    VerbDef("hangup", "hangup", doc="Terminate the call."),
+    VerbDef("redirect", "redirect", doc="Transfer control to a different webhook URL."),
+    VerbDef("pause", "pause", doc="Pause execution for a specified duration."),
+
+    # SIP
+    VerbDef("sip:decline", "sip_decline", doc="Reject incoming call with a SIP error response."),
+    VerbDef("sip:request", "sip_request", doc="Send a SIP request within the current dialog."),
+    VerbDef("sip:refer", "sip_refer", doc="Send a SIP REFER for call transfer."),
+
+    # Utility
+    VerbDef("config", "config", doc="Set session-level defaults."),
+    VerbDef("tag", "tag", doc="Attach metadata to the call."),
+    VerbDef("dtmf", "dtmf", doc="Send DTMF tones."),
+    VerbDef("dub", "dub", doc="Manage audio dubbing tracks."),
+    VerbDef("message", "message", doc="Send SMS/MMS message."),
+    VerbDef("alert", "alert", doc="Send SIP 180 with Alert-Info header."),
+    VerbDef("answer", "answer", doc="Explicitly answer the call."),
+    VerbDef("leave", "leave", doc="Leave a conference or queue."),
+]

jambonz_sdk/webhook/__init__.py

@@ -0,0 +1,10 @@
+"""Webhook (HTTP) transport for jambonz applications."""
+
+from jambonz_sdk.webhook.middleware import env_vars_middleware, verify_signature_middleware
+from jambonz_sdk.webhook.response import WebhookResponse
+
+__all__ = [
+    "WebhookResponse",
+    "env_vars_middleware",
+    "verify_signature_middleware",
+]

jambonz_sdk/webhook/middleware.py

@@ -0,0 +1,63 @@
+"""Middleware utilities for webhook applications.
+
+These are framework-agnostic helpers. For framework-specific integration,
+wrap these in your framework's middleware pattern.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from jambonz_sdk._signature import verify_signature
+
+
+def verify_signature_middleware(
+    payload: bytes,
+    signature_header: str | None,
+    secret: str,
+    tolerance: int = 300,
+) -> bool:
+    """Verify a jambonz webhook signature.
+
+    Args:
+        payload: Raw request body bytes.
+        signature_header: Value of the ``Jambonz-Signature`` header.
+        secret: The webhook signing secret.
+        tolerance: Maximum age in seconds for the timestamp.
+
+    Returns:
+        True if valid.
+
+    Raises:
+        ValueError: If verification fails.
+    """
+    if not signature_header:
+        raise ValueError("Missing Jambonz-Signature header")
+    return verify_signature(payload, signature_header, secret, tolerance)
+
+
+def env_vars_middleware(env_vars: dict[str, dict[str, Any]]) -> dict[str, Any]:
+    """Build the OPTIONS response body for environment variable discovery.
+
+    jambonz sends an OPTIONS request to discover configurable parameters.
+    Return this dict as the JSON response body for OPTIONS requests.
+
+    Args:
+        env_vars: Environment variable schema. Each key is a parameter name,
+            the value describes type, description, default, etc.
+
+    Returns:
+        A dict suitable for JSON serialization as the OPTIONS response body.
+
+    Example::
+
+        env_schema = {
+            "API_KEY": {"type": "string", "description": "API key", "required": True, "obscure": True},
+            "LANGUAGE": {"type": "string", "description": "TTS language", "default": "en-US"},
+        }
+
+        # In your OPTIONS handler:
+        return json.dumps(env_vars_middleware(env_schema))
+    """
+    return {"env": json.loads(json.dumps(env_vars))}

jambonz_sdk/webhook/response.py

@@ -0,0 +1,43 @@
+"""WebhookResponse class for HTTP-based jambonz applications.
+
+Usage with any framework that accepts JSON-serializable responses::
+
+    from jambonz_sdk.webhook import WebhookResponse
+
+    # In your request handler:
+    jambonz = WebhookResponse()
+    jambonz.say(text="Hello!").gather(
+        input=["speech"],
+        actionHook="/handle-input",
+        timeout=10,
+        say={"text": "Please say something."},
+    )
+    # Return jambonz.to_json() as the HTTP response body
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from jambonz_sdk.verb_builder import VerbBuilder
+
+
+class WebhookResponse(VerbBuilder):
+    """Builds a jambonz verb array for HTTP webhook responses.
+
+    Extends VerbBuilder with JSON serialization. The response can be
+    converted to a JSON-serializable list or a JSON string.
+    """
+
+    def to_json(self) -> list[dict[str, Any]]:
+        """Return the verb array as a JSON-serializable list and reset."""
+        return self.to_list()  # type: ignore[return-value]
+
+    def to_json_string(self) -> str:
+        """Return the verb array as a JSON string and reset."""
+        return json.dumps(self.to_list())
+
+    def __json__(self) -> list[dict[str, Any]]:
+        """Support for frameworks that call __json__ for serialization."""
+        return self.to_json()

jambonz_sdk/websocket/__init__.py

@@ -0,0 +1,15 @@
+"""WebSocket transport for jambonz applications."""
+
+from jambonz_sdk.websocket.audio_stream import AudioStream
+from jambonz_sdk.websocket.client import WsClient
+from jambonz_sdk.websocket.endpoint import create_endpoint
+from jambonz_sdk.websocket.router import WsRouter
+from jambonz_sdk.websocket.session import Session
+
+__all__ = [
+    "AudioStream",
+    "Session",
+    "WsClient",
+    "WsRouter",
+    "create_endpoint",
+]

jambonz_sdk/websocket/audio_client.py

@@ -0,0 +1,11 @@
+"""AudioClient - manages audio WebSocket connections.
+
+This module is used internally by the endpoint to handle connections
+on the audio.drachtio.org subprotocol.
+"""
+
+from __future__ import annotations
+
+# AudioClient functionality is handled within the WsRouter and _AudioService
+# classes in router.py. This module is reserved for future audio protocol
+# extensions.

jambonz_sdk/websocket/audio_stream.py

@@ -0,0 +1,151 @@
+"""AudioStream - per-call audio WebSocket handler.
+
+Handles the ``audio.drachtio.org`` subprotocol for streaming raw audio
+between jambonz and the application.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+logger = logging.getLogger("jambonz_sdk.websocket.audio_stream")
+
+AudioHandler = Callable[..., Any]
+
+
+class AudioStream:
+    """Represents a single audio stream WebSocket connection.
+
+    Receives raw L16 PCM audio and JSON text events from jambonz.
+    Can send audio back for bidirectional streaming.
+
+    Events:
+        - ``audio``: Binary L16 PCM frame. Handler receives ``(pcm: bytes)``.
+        - ``dtmf``: DTMF event. Handler receives ``(data: dict)`` with digit and duration.
+        - ``playDone``: Playback completed. Handler receives ``(data: dict)`` with id.
+        - ``mark``: Synchronization marker. Handler receives ``(data: dict)`` with name and event.
+        - ``close``: Connection closed. Handler receives ``(code: int, reason: str)``.
+        - ``error``: Error occurred. Handler receives ``(err: Exception)``.
+
+    Attributes:
+        call_sid: Call identifier.
+        sample_rate: Audio sample rate.
+        metadata: Initial metadata from the connection.
+    """
+
+    def __init__(self, ws: Any) -> None:
+        self._ws = ws
+        self._handlers: dict[str, list[AudioHandler]] = {}
+        self.call_sid: str = ""
+        self.sample_rate: int = 8000
+        self.metadata: dict[str, Any] = {}
+
+    def on(self, event: str, handler: AudioHandler) -> AudioStream:
+        """Register an event handler.
+
+        Returns self for chaining.
+        """
+        if event not in self._handlers:
+            self._handlers[event] = []
+        self._handlers[event].append(handler)
+        return self
+
+    async def _emit(self, event: str, *args: Any) -> None:
+        import asyncio
+
+        for handler in self._handlers.get(event, []):
+            result = handler(*args)
+            if asyncio.iscoroutine(result):
+                await result
+
+    async def _run(self) -> None:
+        """Main message loop for the audio stream."""
+        try:
+            async for message in self._ws:
+                if isinstance(message, bytes):
+                    await self._emit("audio", message)
+                else:
+                    try:
+                        data = json.loads(message)
+                    except json.JSONDecodeError:
+                        continue
+
+                    event_type = data.get("type", "")
+
+                    if event_type == "setup":
+                        self.call_sid = data.get("callSid", "")
+                        self.sample_rate = data.get("sampleRate", 8000)
+                        self.metadata = data.get("metadata", {})
+                    elif event_type == "dtmf":
+                        await self._emit("dtmf", data)
+                    elif event_type == "playDone":
+                        await self._emit("playDone", data)
+                    elif event_type == "mark":
+                        await self._emit("mark", data)
+                    else:
+                        logger.debug("Unhandled audio event: %s", event_type)
+
+        except StopAsyncIteration:
+            await self._emit("close", 1000, "")
+        except Exception as exc:
+            await self._emit("error", exc)
+
+    # ── Sending Audio ───────────────────────────────────────────────
+
+    async def send_audio(self, pcm: bytes) -> None:
+        """Send raw L16 PCM audio back to jambonz (streaming mode)."""
+        await self._ws.send(pcm)
+
+    async def play_audio(
+        self,
+        audio_content: str,
+        *,
+        audio_content_type: str = "raw",
+        sample_rate: int = 8000,
+        id: str | None = None,
+        queue_play: bool = False,
+    ) -> None:
+        """Send a complete audio clip as base64 (non-streaming mode).
+
+        Args:
+            audio_content: Base64-encoded audio content.
+            audio_content_type: ``'raw'`` or ``'wav'``.
+            sample_rate: Audio sample rate in Hz.
+            id: Optional ID returned in the playDone event.
+            queue_play: If True, queue after current playback; if False, interrupt.
+        """
+        msg: dict[str, Any] = {
+            "type": "playAudio",
+            "data": {
+                "audioContent": audio_content,
+                "audioContentType": audio_content_type,
+                "sampleRate": sample_rate,
+                "queuePlay": queue_play,
+            },
+        }
+        if id is not None:
+            msg["data"]["id"] = id
+        await self._ws.send(json.dumps(msg))
+
+    async def kill_audio(self) -> None:
+        """Stop playback and flush the buffer."""
+        await self._ws.send(json.dumps({"type": "killAudio"}))
+
+    async def disconnect(self) -> None:
+        """End the listen/stream verb."""
+        await self._ws.send(json.dumps({"type": "disconnect"}))
+
+    async def send_mark(self, name: str) -> None:
+        """Insert a synchronization marker."""
+        await self._ws.send(json.dumps({"type": "mark", "name": name}))
+
+    async def clear_marks(self) -> None:
+        """Clear all pending markers."""
+        await self._ws.send(json.dumps({"type": "clearMarks"}))
+
+    async def close(self) -> None:
+        """Close the WebSocket connection."""
+        await self._ws.close()

jambonz_sdk/websocket/client.py

@@ -0,0 +1,165 @@
+"""WsClient - manages a jambonz WebSocket service on a specific path."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from jambonz_sdk.websocket.session import EventHandler, Session
+
+logger = logging.getLogger("jambonz_sdk.websocket.client")
+
+
+class WsClient:
+    """Manages a jambonz WebSocket service on a specific path.
+
+    Handles incoming WebSocket connections, creates Session objects for
+    new calls, and routes messages to the appropriate session.
+
+    Events:
+        - ``session:new``: New call session. Handler receives ``(session: Session)``.
+        - ``session:redirect``: Call redirected. Handler receives ``(session: Session)``.
+        - ``error``: Error occurred. Handler receives ``(error: Exception)``.
+    """
+
+    def __init__(self, path: str) -> None:
+        self.path = path
+        self._handlers: dict[str, list[EventHandler]] = {}
+        self._sessions: dict[str, Session] = {}
+
+    def on(self, event: str, handler: EventHandler) -> WsClient:
+        """Register an event handler.
+
+        Args:
+            event: Event name (``'session:new'``, ``'session:redirect'``, ``'error'``).
+            handler: Callback function.
+
+        Returns:
+            self for chaining.
+        """
+        if event not in self._handlers:
+            self._handlers[event] = []
+        self._handlers[event].append(handler)
+        return self
+
+    def _emit(self, event: str, *args: Any) -> bool:
+        """Emit an event to registered handlers."""
+        handlers = self._handlers.get(event, [])
+        for handler in handlers:
+            handler(*args)
+        return bool(handlers)
+
+    async def _emit_async(self, event: str, *args: Any) -> bool:
+        """Emit an event, awaiting async handlers."""
+        import asyncio
+
+        handlers = self._handlers.get(event, [])
+        for handler in handlers:
+            result = handler(*args)
+            if asyncio.iscoroutine(result):
+                await result
+        return bool(handlers)
+
+    async def handle_connection(self, ws: Any) -> None:
+        """Handle a WebSocket connection for this service.
+
+        Processes messages from jambonz and dispatches to the appropriate
+        Session or emits service-level events.
+
+        Args:
+            ws: A WebSocket connection object supporting ``send()``,
+                ``close()``, and async iteration for messages.
+        """
+        session: Session | None = None
+
+        try:
+            async for raw_message in ws:
+                if isinstance(raw_message, bytes):
+                    continue  # Binary frames handled by audio client
+
+                try:
+                    msg = json.loads(raw_message)
+                except json.JSONDecodeError:
+                    logger.warning("Received invalid JSON: %s", raw_message[:100])
+                    continue
+
+                msg_type = msg.get("type", "")
+                msgid = msg.get("msgid", "")
+                data = msg.get("data", {})
+
+                if msg_type in ("session:new", "session:reconnect"):
+                    session = Session(ws, data, msgid)
+                    self._sessions[session.call_sid] = session
+                    await self._emit_async("session:new", session)
+
+                elif msg_type == "session:redirect":
+                    if session:
+                        session._update_msgid(msgid)
+                        session.data = data
+                        await self._emit_async("session:redirect", session)
+                    else:
+                        session = Session(ws, data, msgid)
+                        self._sessions[session.call_sid] = session
+                        await self._emit_async("session:redirect", session)
+
+                elif msg_type == "session:adulting":
+                    # Session is being transferred, just acknowledge
+                    if session:
+                        session._update_msgid(msgid)
+
+                elif msg_type == "verb:hook":
+                    if session:
+                        session._update_msgid(msgid)
+                        hook = msg.get("hook", "")
+                        # Try specific handler first, then fallback
+                        handled = await session._emit_async(hook, data)
+                        if not handled:
+                            handled = await session._emit_async("verb:hook", hook, data)
+                        if not handled:
+                            # Auto-reply with empty verb array
+                            await session.reply()
+
+                elif msg_type == "verb:status":
+                    if session:
+                        await session._emit_async("verb:status", data)
+
+                elif msg_type == "call:status":
+                    if session:
+                        await session._emit_async("call:status", data)
+
+                elif msg_type == "llm:tool-call":
+                    if session:
+                        session._update_msgid(msgid)
+                        await session._emit_async("llm:tool-call", data)
+
+                elif msg_type == "llm:event":
+                    if session:
+                        await session._emit_async("llm:event", data)
+
+                elif msg_type == "tts:tokens-result":
+                    if session:
+                        await session._emit_async("tts:tokens-result", data)
+
+                elif msg_type == "tts:streaming-event":
+                    if session:
+                        event_type = data.get("event_type", "")
+                        # Emit specific event
+                        if event_type:
+                            await session._emit_async(f"tts:{event_type}", data)
+                        # Emit catch-all
+                        await session._emit_async("tts:streaming-event", data)
+
+                else:
+                    logger.debug("Unhandled message type: %s", msg_type)
+
+        except StopAsyncIteration:
+            if session:
+                await session._emit_async("close", 1000, "")
+        except Exception as exc:
+            if session:
+                await session._emit_async("error", exc)
+            await self._emit_async("error", exc)
+        finally:
+            if session and session.call_sid in self._sessions:
+                del self._sessions[session.call_sid]