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

jambonz_sdk/schema/verbs/pipeline.schema.json

@@ -0,0 +1,240 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/pipeline",
+  "minVersion": "10.1.0",
+  "title": "Pipeline",
+  "description": "Configures a complete STT → LLM → TTS voice AI pipeline with integrated turn detection. Provides a higher-level abstraction than manually orchestrating the individual components. Optimized for building voice AI agents with proper turn-taking behavior.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "pipeline"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "stt": {
+      "$ref": "../components/recognizer",
+      "description": "Speech-to-text configuration for the pipeline."
+    },
+    "tts": {
+      "$ref": "../components/synthesizer",
+      "description": "Text-to-speech configuration for the pipeline."
+    },
+    "turnDetection": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": ["stt", "krisp"],
+          "description": "Turn detection strategy shorthand. 'stt' uses the STT vendor's native signals (silence-based for most vendors; acoustic+semantic for deepgramflux, assemblyai, speechmatics). 'krisp' uses the Krisp acoustic end-of-turn model with default settings."
+        },
+        {
+          "type": "object",
+          "description": "Turn detection configuration with tunable parameters.",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["krisp"],
+              "description": "Turn detection mode. Currently only 'krisp' supports object-form tuning."
+            },
+            "threshold": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Krisp end-of-turn confidence threshold (0.0–1.0). Lower values trigger earlier turn transitions. Default: 0.5"
+            },
+            "model": {
+              "type": "string",
+              "description": "Optional Krisp model name override."
+            }
+          },
+          "required": ["mode"],
+          "additionalProperties": false
+        }
+      ],
+      "default": "stt",
+      "description": "Turn detection strategy. Controls when the pipeline decides the user has finished speaking. STT vendors with native turn-taking (deepgramflux, assemblyai, speechmatics) always use their built-in detection regardless of this setting."
+    },
+    "bargeIn": {
+      "type": "object",
+      "description": "Controls whether and how the user can interrupt the assistant while it is speaking.",
+      "properties": {
+        "enable": {
+          "type": "boolean",
+          "description": "Allow the user to interrupt the assistant while it is speaking. Default: true.",
+          "default": true
+        },
+        "minSpeechDuration": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Seconds of detected speech required before confirming an interruption. Prevents brief noises from cutting off the assistant. Default: 0.5",
+          "default": 0.5
+        },
+        "sticky": {
+          "type": "boolean",
+          "description": "If true, once the user interrupts the assistant does not resume speaking. Default: false.",
+          "default": false
+        }
+      },
+      "additionalProperties": true
+    },
+    "noResponseTimeout": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Seconds to wait after the assistant finishes speaking before prompting the user to respond. 0 disables. Default: 0.",
+      "default": 0
+    },
+    "llm": {
+      "type": "object",
+      "description": "LLM configuration for the pipeline. See the 'llm' verb schema for details.",
+      "additionalProperties": true
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the pipeline ends."
+    },
+    "eventHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked for pipeline events. Receives event types: 'user_transcript' (user speech recognized), 'agent_response' (assistant reply), 'user_interruption' (barge-in detected), and 'turn_end' (end-of-turn summary with transcript, response, and latency metrics)."
+    },
+    "toolHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook invoked when the LLM requests a tool/function call. The payload includes the tool name and arguments; the response provides the tool result."
+    },
+    "greeting": {
+      "type": "boolean",
+      "description": "Whether the LLM should generate an initial greeting before the user speaks. Default: true.",
+      "default": true
+    },
+    "earlyGeneration": {
+      "type": "boolean",
+      "description": "Enable speculative LLM prompting before end-of-turn is confirmed. When using Krisp turn detection, set this to true to speculatively prompt the LLM before Krisp confirms the turn has ended. If the transcript matches when turn ends, buffered tokens are released immediately — reducing response latency. Note: Deepgram Flux performs early generation automatically via its native EagerEndOfTurn signal regardless of this setting. Default: false.",
+      "default": false
+    },
+    "noiseIsolation": {
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": ["krisp", "rnnoise"],
+          "description": "Shorthand — enable noise isolation with the specified vendor using default settings."
+        },
+        {
+          "type": "object",
+          "description": "Detailed noise isolation configuration.",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "description": "Noise isolation vendor/mode (e.g. 'krisp')."
+            },
+            "level": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 100,
+              "description": "Suppression level 0–100. Default: 100."
+            },
+            "direction": {
+              "type": "string",
+              "enum": ["read", "write"],
+              "description": "Audio direction to apply noise isolation. 'read' filters caller audio, 'write' filters outbound audio. Default: 'read'."
+            },
+            "model": {
+              "type": "string",
+              "description": "Optional model name override."
+            }
+          },
+          "required": ["mode"],
+          "additionalProperties": false
+        }
+      ],
+      "description": "Enable server-side noise isolation to reduce background noise on call audio. Defaults to filtering inbound (caller) audio; set direction to 'write' for outbound. Useful for improving STT accuracy in noisy environments."
+    },
+    "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": "External MCP servers that provide tools to the LLM. The pipeline connects at startup via SSE, discovers available tools, and makes them callable by the LLM."
+    }
+  },
+  "required": [
+    "llm"
+  ],
+  "examples": [
+    {
+      "verb": "pipeline",
+      "stt": {
+        "vendor": "deepgram",
+        "language": "en-US"
+      },
+      "tts": {
+        "vendor": "cartesia",
+        "voice": "sonic-english"
+      },
+      "llm": {
+        "vendor": "openai",
+        "model": "gpt-4o",
+        "llmOptions": {
+          "messages": [
+            {
+              "role": "system",
+              "content": "You are a helpful voice assistant."
+            }
+          ]
+        }
+      },
+      "turnDetection": "stt",
+      "actionHook": "/pipeline-complete"
+    },
+    {
+      "verb": "pipeline",
+      "stt": {
+        "vendor": "deepgram",
+        "language": "en-US"
+      },
+      "tts": {
+        "vendor": "cartesia",
+        "voice": "sonic-english"
+      },
+      "llm": {
+        "vendor": "anthropic",
+        "model": "claude-opus-4-6",
+        "llmOptions": {
+          "messages": [
+            {
+              "role": "user",
+              "content": "You are a helpful voice assistant."
+            }
+          ]
+        }
+      },
+      "turnDetection": {
+        "mode": "krisp",
+        "threshold": 0.3
+      },
+      "bargeIn": {
+        "enable": true,
+        "minSpeechDuration": 0.3,
+        "sticky": false
+      },
+      "actionHook": "/pipeline-complete"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/play.schema.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/play",
+  "minVersion": "0.9.6",
+  "title": "Play",
+  "description": "Plays an audio file to the caller. Supports WAV and MP3 formats hosted at a URL. Can play a single file or cycle through a list of files.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "play",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "url": {
+      "oneOf": [
+        {
+          "type": "string",
+          "format": "uri"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uri"
+          }
+        }
+      ],
+      "description": "The URL(s) of the audio file(s) to play. Supports WAV and MP3. If an array, files are played in sequence.",
+      "examples": [
+        "https://example.com/sounds/greeting.wav",
+        [
+          "https://example.com/sounds/part1.wav",
+          "https://example.com/sounds/part2.wav"
+        ]
+      ]
+    },
+    "loop": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Number of times to repeat playback. Use 0 or 'forever' to loop indefinitely until interrupted.",
+      "examples": [
+        3,
+        "forever"
+      ]
+    },
+    "earlyMedia": {
+      "type": "boolean",
+      "description": "If true, play the audio as early media before the call is answered."
+    },
+    "seekOffset": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Start playback at this offset in seconds from the beginning of the file."
+    },
+    "timeoutSecs": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Maximum time in seconds to play the audio. Playback stops after this duration even if the file has not finished."
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to invoke when playback completes."
+    }
+  },
+  "required": [
+    "url"
+  ],
+  "examples": [
+    {
+      "verb": "play",
+      "url": "https://example.com/sounds/hold-music.mp3",
+      "loop": "forever"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/redirect.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/redirect",
+  "minVersion": "0.9.6",
+  "title": "Redirect",
+  "description": "Transfers call control to a different webhook URL. The current verb stack is abandoned and the new webhook's response becomes the active application. Useful for modular application design where different URLs handle different phases of a call.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "redirect"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "actionHook": {
+      "$ref": "../components/actionHook",
+      "description": "The webhook to transfer control to. Must return a new array of verbs."
+    },
+    "statusHook": {
+      "$ref": "../components/actionHook",
+      "description": "A webhook to receive call status events after the redirect."
+    }
+  },
+  "required": [
+    "actionHook"
+  ],
+  "examples": [
+    {
+      "verb": "redirect",
+      "actionHook": "/new-handler"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/rest_dial.schema.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/rest:dial",
+  "title": "REST Dial",
+  "description": "Internal verb used to originate an outbound call via the REST API. Not typically used directly in application verb arrays.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "rest:dial"
+    },
+    "id": {
+      "type": "string"
+    },
+    "account_sid": {
+      "type": "string"
+    },
+    "application_sid": {
+      "type": "string"
+    },
+    "call_hook": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object" }
+      ],
+      "description": "Webhook URL or object for call control."
+    },
+    "call_status_hook": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object" }
+      ],
+      "description": "Webhook URL or object for call status notifications."
+    },
+    "from": {
+      "type": "string",
+      "description": "The caller ID for the outbound call."
+    },
+    "callerName": {
+      "type": "string",
+      "description": "Display name for the caller."
+    },
+    "fromHost": {
+      "type": "string",
+      "description": "SIP host to use in the From header."
+    },
+    "speech_synthesis_vendor": {
+      "type": "string"
+    },
+    "speech_synthesis_voice": {
+      "type": "string"
+    },
+    "speech_synthesis_language": {
+      "type": "string"
+    },
+    "speech_recognizer_vendor": {
+      "type": "string"
+    },
+    "speech_recognizer_language": {
+      "type": "string"
+    },
+    "tag": {
+      "type": "object",
+      "description": "Arbitrary metadata to attach to the call.",
+      "additionalProperties": true
+    },
+    "to": {
+      "$ref": "../components/target",
+      "description": "The call destination."
+    },
+    "headers": {
+      "type": "object",
+      "description": "Custom SIP headers to include on the outbound INVITE.",
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string" },
+          { "type": "number" }
+        ]
+      }
+    },
+    "timeout": {
+      "type": "number",
+      "description": "Ring timeout in seconds."
+    },
+    "amd": {
+      "$ref": "../components/amd",
+      "description": "Answering machine detection configuration."
+    },
+    "dual_streams": {
+      "type": "boolean",
+      "description": "If true, send separate audio streams for each call leg."
+    },
+    "sipRequestWithinDialogHook": {
+      "type": "string",
+      "description": "Webhook for in-dialog SIP requests."
+    },
+    "referHook": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object" }
+      ],
+      "description": "Webhook for SIP REFER handling."
+    },
+    "timeLimit": {
+      "type": "number",
+      "description": "Maximum call duration in seconds."
+    }
+  },
+  "required": [
+    "call_hook",
+    "from",
+    "to"
+  ]
+}

jambonz_sdk/schema/verbs/s2s.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/s2s",
+  "minVersion": "10.1.0",
+  "title": "S2S",
+  "description": "Synonym for 'llm'. Connects the caller to a large language model for a real-time speech-to-speech voice conversation. Requires 'vendor' to be specified explicitly.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "../components/llm-base"
+    }
+  ],
+  "properties": {
+    "verb": {
+      "const": "s2s",
+      "description": "The verb name."
+    }
+  },
+  "required": [
+    "vendor",
+    "llmOptions"
+  ],
+  "examples": [
+    {
+      "verb": "s2s",
+      "vendor": "openai",
+      "model": "gpt-4o-realtime",
+      "llmOptions": {
+        "messages": [
+          {
+            "role": "system",
+            "content": "You are a helpful voice assistant."
+          }
+        ]
+      },
+      "actionHook": "/s2s-complete"
+    }
+  ]
+}

jambonz_sdk/schema/verbs/say.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/say",
+  "minVersion": "0.9.6",
+  "title": "Say",
+  "description": "Speaks text to the caller using text-to-speech. The text can be plain text or SSML. Optionally streams TTS output incrementally for lower latency. This is one of the most commonly used verbs in jambonz applications.",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "say",
+      "description": "The verb name."
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance. Can be used to reference it in other contexts."
+    },
+    "text": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ],
+      "description": "The text to speak. Can be plain text or SSML markup. If an array is provided, one entry is selected at random (useful for variety in prompts).",
+      "examples": [
+        "Hello, welcome to our service.",
+        "<speak>Hello <break time='500ms'/> welcome.</speak>",
+        [
+          "Hello!",
+          "Hi there!",
+          "Welcome!"
+        ]
+      ]
+    },
+    "instructions": {
+      "type": "string",
+      "description": "Natural language instructions to guide TTS expression and delivery. Supported by vendors that offer instruction-based synthesis (e.g. ElevenLabs, some OpenAI models).",
+      "examples": [
+        "Speak in a warm, friendly tone",
+        "Sound excited and energetic"
+      ]
+    },
+    "stream": {
+      "type": "boolean",
+      "description": "If true, stream TTS audio to the caller incrementally as it is generated, rather than waiting for the complete audio. Reduces time-to-first-byte for long utterances. Requires a vendor that supports streaming synthesis."
+    },
+    "loop": {
+      "oneOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "Number of times to repeat the speech. Use 0 or 'forever' to loop indefinitely until interrupted.",
+      "examples": [
+        2,
+        "forever"
+      ]
+    },
+    "synthesizer": {
+      "$ref": "../components/synthesizer",
+      "description": "Override the session-level TTS configuration for this specific utterance."
+    },
+    "earlyMedia": {
+      "type": "boolean",
+      "description": "If true, play the audio as early media (before the call is answered). Used for playing announcements or prompts to the caller before the call is formally connected."
+    },
+    "disableTtsCache": {
+      "type": "boolean",
+      "description": "If true, bypass the TTS cache and always generate fresh audio. Useful when the same text should be re-synthesized (e.g. with different SSML or when the voice has been updated)."
+    },
+    "closeStreamOnEmpty": {
+      "type": "boolean",
+      "description": "If true, close the TTS stream when an empty text string is received. Only applies when stream is true."
+    }
+  },
+  "examples": [
+    {
+      "verb": "say",
+      "text": "Hello, welcome to Acme Corp. How can I help you today?"
+    },
+    {
+      "verb": "say",
+      "text": "Please hold while I transfer your call.",
+      "synthesizer": {
+        "vendor": "elevenlabs",
+        "voice": "Rachel"
+      }
+    },
+    {
+      "verb": "say",
+      "text": [
+        "Hello!",
+        "Hi there!",
+        "Welcome!"
+      ],
+      "loop": 1
+    }
+  ]
+}

jambonz_sdk/schema/verbs/sip-decline.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/verbs/sip:decline",
+  "minVersion": "0.9.6",
+  "title": "SIP Decline",
+  "description": "Rejects an incoming call with a SIP error response. Used to decline calls with a specific status code and reason (e.g. 486 Busy Here, 603 Decline).",
+  "type": "object",
+  "properties": {
+    "verb": {
+      "const": "sip:decline"
+    },
+    "id": {
+      "type": "string",
+      "description": "An optional unique identifier for this verb instance."
+    },
+    "status": {
+      "type": "number",
+      "description": "The SIP response status code to send.",
+      "examples": [
+        486,
+        603,
+        404,
+        480
+      ]
+    },
+    "reason": {
+      "type": "string",
+      "description": "The SIP reason phrase to include in the response.",
+      "examples": [
+        "Busy Here",
+        "Decline",
+        "Not Found"
+      ]
+    },
+    "headers": {
+      "type": "object",
+      "description": "Custom SIP headers to include in the response.",
+      "additionalProperties": {
+        "oneOf": [{ "type": "string" }, { "type": "number" }]
+      }
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "examples": [
+    {
+      "verb": "sip:decline",
+      "status": 486,
+      "reason": "Busy Here"
+    },
+    {
+      "verb": "sip:decline",
+      "status": 603,
+      "reason": "Decline"
+    }
+  ]
+}