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

jambonz_sdk/schema/callbacks/tts-streaming-event.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/tts-streaming-event",
+  "title": "TTS Streaming Event",
+  "description": "Events sent to the '/streaming-event' WebSocket endpoint during TTS streaming. These are sent as 'tts:streaming-event' messages. The tts_spoken event is only sent when trackTtsPlayout is enabled via the config verb.",
+  "type": "object",
+  "oneOf": [
+    {
+      "properties": {
+        "event_type": {
+          "const": "stream_open",
+          "description": "The TTS streaming connection has been established."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "stream_closed",
+          "description": "The TTS streaming connection has been closed."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "stream_paused",
+          "description": "TTS streaming has been paused."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "stream_resumed",
+          "description": "TTS streaming has been resumed."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "user_interruption",
+          "description": "The user interrupted (barged in) during TTS playout, causing the stream to be cleared."
+        }
+      },
+      "required": ["event_type"],
+      "additionalProperties": false
+    },
+    {
+      "properties": {
+        "event_type": {
+          "const": "tts_spoken",
+          "description": "Reports the actual text that was spoken via TTS. Sent on utterance completion or when the user barges in. Only sent when trackTtsPlayout is enabled via the config verb. Requires a TTS vendor that supports alignment data (e.g. ElevenLabs)."
+        },
+        "text": {
+          "type": "string",
+          "description": "The text that was actually spoken before completion or interruption."
+        },
+        "bargein": {
+          "type": "boolean",
+          "description": "True if the user barged in (interrupted) before the TTS finished speaking. False if the utterance completed normally."
+        }
+      },
+      "required": ["event_type", "text", "bargein"],
+      "additionalProperties": false
+    }
+  ]
+}

jambonz_sdk/schema/callbacks/verb-status.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/verb-status",
+  "title": "Verb Status Event",
+  "description": "Real-time verb lifecycle events sent over WebSocket when notifyEvents is enabled on the session. These are informational — no response is expected.",
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "enum": [
+        "starting",
+        "finished",
+        "start-playback",
+        "stop-playback",
+        "kill-playback",
+        "dtmf-bargein-detected",
+        "speech-bargein-detected",
+        "synthesized-audio"
+      ],
+      "description": "The verb lifecycle event."
+    },
+    "verb": {
+      "type": "string",
+      "description": "The verb name (e.g. 'say', 'play', 'gather'). Present on synthesized-audio, start-playback, stop-playback, kill-playback, and dtmf/speech-bargein events."
+    },
+    "name": {
+      "type": "string",
+      "description": "The verb name. Present on 'starting' and 'finished' events (these use 'name' instead of 'verb')."
+    },
+    "id": {
+      "type": "string",
+      "description": "The verb instance id, if one was assigned by the application."
+    },
+    "vendor": {
+      "type": "string",
+      "description": "TTS vendor name. Present on synthesized-audio events."
+    },
+    "language": {
+      "type": "string",
+      "description": "TTS language code. Present on synthesized-audio events."
+    },
+    "characters": {
+      "type": "integer",
+      "description": "Number of characters synthesized. Present on synthesized-audio events when not served from cache."
+    },
+    "elapsed_time": {
+      "type": "number",
+      "description": "TTS round-trip time in milliseconds. Present on synthesized-audio events when not served from cache."
+    },
+    "served_from_cache": {
+      "type": "boolean",
+      "description": "Whether the TTS audio was served from cache. Present on synthesized-audio events."
+    }
+  },
+  "required": ["event"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/components/actionHook.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/actionHook",
+  "title": "ActionHook",
+  "description": "A webhook or websocket callback that jambonz invokes when a verb completes. Reports verb results (e.g. speech recognition from 'gather', dial outcome) and receives the next verbs to execute. In webhook mode: jambonz POSTs to this URL and the HTTP response body is the next verb array. In WebSocket mode: this value becomes an event name emitted on the session — bind session.on('/hookName', (evt) => {...}) and respond with session.reply() (NOT session.send()). The callback payload always includes 'reason' plus verb-specific fields (e.g. 'speech', 'digits' for gather). Can be a simple URL/path string or an object with additional options.",
+  "oneOf": [
+    {
+      "type": "string",
+      "format": "uri",
+      "description": "A URL to invoke. For webhook applications this is an HTTP(S) URL. For websocket applications this is typically a relative path or event name.",
+      "examples": ["https://myapp.example.com/gather-result", "/gather-result"]
+    },
+    {
+      "type": "object",
+      "description": "A hook specification with URL and additional options.",
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "The URL to invoke."
+        },
+        "method": {
+          "type": "string",
+          "description": "The HTTP method to use. Only applies to webhook applications.",
+          "enum": ["GET", "POST"],
+          "default": "POST"
+        },
+        "basicAuth": {
+          "$ref": "auth",
+          "description": "Basic authentication credentials to include in the request."
+        }
+      },
+      "required": ["url"]
+    }
+  ]
+}

jambonz_sdk/schema/components/actionHookDelayAction.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/actionHookDelayAction",
+  "title": "ActionHookDelayAction",
+  "description": "Configuration for what to do when an actionHook (webhook) takes a long time to respond. Allows playing interim content (e.g. 'please wait' messages, hold music) while waiting for the webhook response, with configurable retry and give-up behavior.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether to enable delay handling for actionHooks."
+    },
+    "noResponseTimeout": {
+      "type": "number",
+      "description": "Time in seconds to wait before executing the delay actions. If the webhook responds before this timeout, the delay actions are skipped.",
+      "examples": [3, 5]
+    },
+    "noResponseGiveUpTimeout": {
+      "type": "number",
+      "description": "Total time in seconds to wait for a webhook response before giving up and executing the giveUpActions.",
+      "examples": [30, 60]
+    },
+    "retries": {
+      "type": "number",
+      "description": "Number of times to retry the delay actions while still waiting for the webhook response."
+    },
+    "actions": {
+      "type": "array",
+      "description": "An array of jambonz verbs to execute while waiting for the webhook response. Typically 'say' or 'play' verbs with messages like 'please hold'.",
+      "items": { "type": "object" }
+    },
+    "giveUpActions": {
+      "type": "array",
+      "description": "An array of jambonz verbs to execute if the webhook never responds within the giveUpTimeout. Typically an error message and/or hangup.",
+      "items": { "type": "object" }
+    }
+  }
+}

jambonz_sdk/schema/components/amd.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/amd",
+  "title": "Answering Machine Detection",
+  "description": "Configuration for answering machine detection (AMD). Detects whether an outbound or inbound call was answered by a human or a machine. Used as a nested property on the 'config' or 'dial' verb. IMPORTANT: AMD runs asynchronously in the background. When using AMD with the 'config' verb, you MUST follow it with a 'pause' verb (e.g. pause({ length: 25 })) to keep the call alive while AMD detection runs. Without a pause, the call will end immediately after config completes.",
+  "type": "object",
+  "properties": {
+    "actionHook": {
+      "$ref": "actionHook",
+      "description": "Webhook to receive AMD events (amd_human_detected, amd_machine_detected, amd_no_speech_detected, amd_decision_timeout, amd_machine_stopped_speaking, amd_tone_detected, amd_error, amd_stopped)."
+    },
+    "thresholdWordCount": {
+      "type": "number",
+      "description": "Number of spoken words in a greeting that triggers an amd_machine_detected result.",
+      "default": 9
+    },
+    "digitCount": {
+      "type": "number",
+      "description": "Number of digits in a greeting to trigger detection. 0 disables digit-based detection.",
+      "default": 0
+    },
+    "timers": {
+      "type": "object",
+      "description": "Timer settings controlling AMD detection windows.",
+      "properties": {
+        "noSpeechTimeoutMs": {
+          "type": "number",
+          "description": "Milliseconds to wait for any speech before returning amd_no_speech_detected.",
+          "default": 5000
+        },
+        "decisionTimeoutMs": {
+          "type": "number",
+          "description": "Milliseconds before returning amd_decision_timeout if no determination is made.",
+          "default": 15000
+        },
+        "toneTimeoutMs": {
+          "type": "number",
+          "description": "Milliseconds to wait for beep/tone detection.",
+          "default": 20000
+        },
+        "greetingCompletionTimeoutMs": {
+          "type": "number",
+          "description": "Milliseconds of silence after speech before determining the machine greeting is complete. Automatically reduced to 1000ms if a beep is detected.",
+          "default": 2000
+        }
+      },
+      "additionalProperties": false
+    },
+    "recognizer": {
+      "$ref": "recognizer",
+      "description": "Override the STT recognizer used for AMD speech detection. When omitted, AMD uses the session default recognizer with enhancedModel enabled."
+    }
+  },
+  "required": ["actionHook"],
+  "examples": [
+    {
+      "actionHook": "/amd-events"
+    },
+    {
+      "actionHook": "/amd-events",
+      "thresholdWordCount": 6,
+      "timers": {
+        "noSpeechTimeoutMs": 3000,
+        "decisionTimeoutMs": 10000
+      }
+    }
+  ]
+}

jambonz_sdk/schema/components/auth.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/auth",
+  "title": "Auth",
+  "description": "Basic authentication credentials, used for authenticating with external services such as websocket endpoints or SIP registrars.",
+  "type": "object",
+  "properties": {
+    "username": {
+      "type": "string",
+      "description": "The username for authentication."
+    },
+    "password": {
+      "type": "string",
+      "description": "The password for authentication."
+    }
+  },
+  "required": ["username", "password"]
+}

jambonz_sdk/schema/components/bidirectionalAudio.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/bidirectionalAudio",
+  "title": "BidirectionalAudio",
+  "description": "Configuration for bidirectional audio streaming over a websocket connection. When enabled, the remote websocket endpoint can send audio back to jambonz to be played to the caller.",
+  "type": "object",
+  "properties": {
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether to enable bidirectional audio on the websocket connection."
+    },
+    "streaming": {
+      "type": "boolean",
+      "description": "If true, audio is streamed continuously rather than sent as complete messages."
+    },
+    "sampleRate": {
+      "type": "number",
+      "description": "The sample rate in Hz for bidirectional audio.",
+      "examples": [8000, 16000, 24000]
+    }
+  }
+}

jambonz_sdk/schema/components/fillerNoise.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/fillerNoise",
+  "title": "FillerNoise",
+  "description": "Configuration for playing background filler noise (e.g. keyboard typing, hold music) while the application is processing and the caller would otherwise hear silence. Commonly used during LLM response generation to indicate the system is working.",
+  "type": "object",
+  "properties": {
+    "enable": {
+      "type": "boolean",
+      "description": "Whether to enable filler noise."
+    },
+    "url": {
+      "type": "string",
+      "format": "uri",
+      "description": "URL of the audio file to play as filler noise. Should be a short, loopable audio clip.",
+      "examples": ["https://example.com/sounds/typing.wav"]
+    },
+    "startDelaySecs": {
+      "type": "number",
+      "description": "Number of seconds to wait before starting filler noise. Prevents filler noise from playing during brief processing pauses.",
+      "examples": [1, 2]
+    }
+  },
+  "required": ["enable"]
+}

jambonz_sdk/schema/components/llm-base.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/llm-base",
+  "title": "LLM Base Properties",
+  "description": "Shared properties for llm, s2s, and vendor-specific s2s verb schemas.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "vendor": {
+      "type": "string",
+      "description": "The LLM vendor to use.",
+      "examples": ["openai", "anthropic", "google", "groq", "deepseek", "deepgram", "ultravox", "custom"]
+    },
+    "model": {
+      "type": "string",
+      "description": "The specific model to use from the vendor.",
+      "examples": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-2.0-flash"]
+    },
+    "auth": {
+      "type": "object",
+      "description": "Authentication credentials for the LLM vendor API.",
+      "properties": {
+        "apiKey": {
+          "type": "string",
+          "description": "The API key for the LLM vendor."
+        }
+      },
+      "additionalProperties": true
+    },
+    "connectOptions": {
+      "type": "object",
+      "description": "Additional connection options for the LLM vendor, such as custom base URLs or API versions.",
+      "additionalProperties": true
+    },
+    "llmOptions": {
+      "type": "object",
+      "description": "Configuration passed to the LLM including the system prompt, temperature, tools/functions, and other model parameters. The structure varies by vendor but typically includes 'messages' (conversation history), 'temperature', 'tools' (function definitions), and 'maxTokens'.",
+      "additionalProperties": true,
+      "examples": [
+        {
+          "messages": [
+            { "role": "system", "content": "You are a helpful customer service agent for Acme Corp." }
+          ],
+          "temperature": 0.7
+        }
+      ]
+    },
+    "mcpServers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "format": "uri",
+            "description": "The URL of the MCP server."
+          },
+          "auth": {
+            "type": "object",
+            "description": "Authentication for the MCP server.",
+            "additionalProperties": true
+          },
+          "roots": {
+            "type": "array",
+            "items": { "type": "object" },
+            "description": "MCP root definitions."
+          }
+        },
+        "required": ["url"]
+      },
+      "description": "Model Context Protocol servers to connect to. MCP servers provide tools that the LLM can invoke during the conversation."
+    },
+    "actionHook": {
+      "$ref": "actionHook",
+      "description": "A webhook invoked when the LLM conversation ends. Receives conversation details and should return the next verbs to execute."
+    },
+    "eventHook": {
+      "$ref": "actionHook",
+      "description": "A webhook invoked for real-time events during the LLM conversation (e.g. tool calls, transcription events)."
+    },
+    "toolHook": {
+      "$ref": "actionHook",
+      "description": "A webhook invoked when the LLM calls a tool/function. Receives the tool name and arguments, and should return the tool result."
+    },
+    "events": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of event types to receive via the eventHook."
+    }
+  }
+}

jambonz_sdk/schema/components/recognizer-assemblyAiOptions.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-assemblyAiOptions",
+  "title": "AssemblyAI Recognizer Options",
+  "description": "AssemblyAI-specific STT options. Only applies when recognizer vendor is 'assemblyai'.",
+  "type": "object",
+  "properties": {
+    "apiKey": {
+      "type": "string",
+      "description": "AssemblyAI API key. Overrides credentials configured in jambonz."
+    },
+    "serviceVersion": {
+      "type": "string",
+      "enum": ["v2", "v3"],
+      "description": "AssemblyAI streaming API version."
+    },
+    "speechModel": {
+      "type": "string",
+      "description": "AssemblyAI speech model to use for recognition."
+    },
+    "formatTurns": {
+      "type": "boolean",
+      "description": "Enable turn-level formatting."
+    },
+    "endOfTurnConfidenceThreshold": {
+      "type": "number",
+      "description": "Confidence threshold for end-of-turn detection."
+    },
+    "minEndOfTurnSilenceWhenConfident": {
+      "type": "number",
+      "description": "Minimum silence duration (seconds) to trigger end-of-turn when confidence is met."
+    },
+    "maxTurnSilence": {
+      "type": "number",
+      "description": "Maximum silence duration (seconds) before forcing end-of-turn."
+    },
+    "minTurnSilence": {
+      "type": "number",
+      "description": "Minimum silence duration (seconds) before allowing end-of-turn."
+    },
+    "keyterms": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "List of key terms to boost in recognition."
+    },
+    "prompt": {
+      "type": "string",
+      "description": "Prompt to guide the recognition model."
+    },
+    "languageDetection": {
+      "type": "boolean",
+      "description": "Enable automatic language detection."
+    },
+    "vadThreshold": {
+      "type": "number",
+      "description": "Voice activity detection threshold."
+    },
+    "inactivityTimeout": {
+      "type": "number",
+      "description": "Timeout (seconds) for inactivity before closing the stream."
+    }
+  },
+  "additionalProperties": false
+}

jambonz_sdk/schema/components/recognizer-awsOptions.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-awsOptions",
+  "title": "AWS Recognizer Options",
+  "description": "AWS Transcribe specific options. Only applies when recognizer vendor is 'aws'.",
+  "type": "object",
+  "properties": {
+    "accessKey": {
+      "type": "string",
+      "description": "AWS access key ID. Overrides credentials configured in jambonz."
+    },
+    "secretKey": {
+      "type": "string",
+      "description": "AWS secret access key."
+    },
+    "securityToken": {
+      "type": "string",
+      "description": "AWS temporary security token (for STS/assumed roles)."
+    },
+    "region": {
+      "type": "string",
+      "description": "AWS region for the Transcribe service."
+    },
+    "vocabularyName": {
+      "type": "string",
+      "description": "Name of a custom vocabulary to use."
+    },
+    "vocabularyFilterName": {
+      "type": "string",
+      "description": "Name of a vocabulary filter to apply."
+    },
+    "vocabularyFilterMethod": {
+      "type": "string",
+      "enum": ["remove", "mask", "tag"],
+      "description": "How filtered vocabulary words should be handled."
+    },
+    "languageModelName": {
+      "type": "string",
+      "description": "Name of a custom language model."
+    },
+    "piiEntityTypes": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "PII entity types to identify (e.g. 'BANK_ACCOUNT_NUMBER', 'CREDIT_DEBIT_NUMBER')."
+    },
+    "piiIdentifyEntities": {
+      "type": "boolean",
+      "description": "Enable PII entity identification."
+    }
+  },
+  "additionalProperties": false
+}

jambonz_sdk/schema/components/recognizer-azureOptions.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-azureOptions",
+  "title": "Azure Recognizer Options",
+  "description": "Azure Speech Services specific options. Only applies when recognizer vendor is 'microsoft'.",
+  "type": "object",
+  "properties": {
+    "speechSegmentationSilenceTimeoutMs": {
+      "type": "number",
+      "description": "Silence timeout in milliseconds for speech segmentation."
+    },
+    "postProcessing": {
+      "type": "string",
+      "description": "Post-processing mode for transcription results."
+    },
+    "audioLogging": {
+      "type": "boolean",
+      "description": "Enable audio logging for diagnostics."
+    },
+    "languageIdMode": {
+      "type": "string",
+      "enum": ["AtStart", "Continuous"],
+      "description": "Language identification mode when using multiple languages."
+    },
+    "speechRecognitionMode": {
+      "type": "string",
+      "enum": ["CONVERSATION", "DICTATION", "INTERACTIVE"],
+      "description": "Speech recognition mode optimized for the interaction type."
+    }
+  },
+  "additionalProperties": false
+}

jambonz_sdk/schema/components/recognizer-cobaltOptions.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-cobaltOptions",
+  "title": "Cobalt Recognizer Options",
+  "description": "Cobalt-specific STT options. Only applies when recognizer vendor is 'cobalt'.",
+  "type": "object",
+  "properties": {
+    "serverUri": {
+      "type": "string",
+      "description": "Cobalt server URI."
+    },
+    "enableConfusionNetwork": {
+      "type": "boolean",
+      "description": "Enable confusion network output."
+    },
+    "metadata": {
+      "type": "string",
+      "description": "Metadata string to pass to the server."
+    },
+    "compiledContextData": {
+      "type": "string",
+      "description": "Compiled context data for biasing recognition."
+    },
+    "wordTimeOffsets": {
+      "type": "boolean",
+      "description": "Include word-level timestamps."
+    },
+    "contextToken": {
+      "type": "string",
+      "description": "Context token for server-side context."
+    }
+  },
+  "additionalProperties": false
+}

jambonz_sdk/schema/components/recognizer-customOptions.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/components/recognizer-customOptions",
+  "title": "Custom Recognizer Options",
+  "description": "Options for custom STT vendors. Only applies when recognizer vendor is 'custom'.",
+  "type": "object",
+  "properties": {
+    "authToken": {
+      "type": "string",
+      "description": "Authentication token for the custom STT service."
+    },
+    "uri": {
+      "type": "string",
+      "description": "WebSocket URI of the custom STT service."
+    },
+    "sampleRate": {
+      "type": "number",
+      "description": "Audio sample rate in Hz."
+    },
+    "options": {
+      "type": "object",
+      "description": "Additional vendor-specific options passed through to the custom service.",
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": false
+}