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

jambonz_sdk/client/api.py

@@ -0,0 +1,241 @@
+"""JambonzClient - REST API client for jambonz platform management and call control.
+
+Provides typed methods for creating calls, querying active calls,
+and mid-call control (redirect, whisper, mute, etc.).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import aiohttp
+
+
+class _Resource:
+    """Base class for API resources."""
+
+    def __init__(self, client: JambonzClient, path: str) -> None:
+        self._client = client
+        self._path = path
+
+    async def _request(
+        self,
+        method: str,
+        path: str = "",
+        *,
+        json: Any = None,
+        params: dict[str, str] | None = None,
+    ) -> Any:
+        return await self._client._request(
+            method, f"{self._path}{path}", json=json, params=params
+        )
+
+
+class CallsResource(_Resource):
+    """REST API operations for active calls."""
+
+    def __init__(self, client: JambonzClient) -> None:
+        super().__init__(client, "/Calls")
+
+    async def create(self, opts: dict[str, Any]) -> str:
+        """Create an outbound call.
+
+        Args:
+            opts: Call options including ``from``, ``to``, ``call_hook``, etc.
+
+        Returns:
+            The call_sid of the created call.
+        """
+        result = await self._request("POST", json=opts)
+        return result.get("sid", result.get("call_sid", ""))
+
+    async def list(self, filter: dict[str, str] | None = None) -> list[dict[str, Any]]:
+        """List active calls.
+
+        Args:
+            filter: Optional filter by direction, from, to, callStatus.
+        """
+        return await self._request("GET", params=filter)
+
+    async def get(self, call_sid: str) -> dict[str, Any]:
+        """Get information about a specific call."""
+        return await self._request("GET", f"/{call_sid}")
+
+    async def count(self) -> dict[str, int]:
+        """Get count of inbound/outbound calls."""
+        return await self._request("GET", "/count")
+
+    async def update(self, call_sid: str, opts: dict[str, Any]) -> dict[str, Any]:
+        """Update an active call (generic)."""
+        return await self._request("PUT", f"/{call_sid}", json=opts)
+
+    async def delete(self, call_sid: str) -> None:
+        """Terminate a call."""
+        await self._request("DELETE", f"/{call_sid}")
+
+    async def redirect(self, call_sid: str, hook: str) -> dict[str, Any]:
+        """Redirect a call to a new webhook.
+
+        Args:
+            call_sid: The call to redirect.
+            hook: URL of the new webhook.
+        """
+        return await self.update(call_sid, {"call_hook": hook})
+
+    async def whisper(self, call_sid: str, verb: dict[str, Any]) -> dict[str, Any]:
+        """Inject a whisper verb (say/play) into the call.
+
+        Args:
+            call_sid: The call to whisper to.
+            verb: A verb dict (e.g., ``{"verb": "say", "text": "Hello"}``).
+        """
+        return await self.update(call_sid, {"whisper": verb})
+
+    async def mute(self, call_sid: str, status: str) -> dict[str, Any]:
+        """Mute or unmute a call.
+
+        Args:
+            call_sid: The call to mute.
+            status: ``'mute'`` or ``'unmute'``.
+        """
+        return await self.update(call_sid, {"mute_status": status})
+
+    async def update_pipeline(
+        self, call_sid: str, data: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Send a mid-conversation pipeline update.
+
+        Args:
+            call_sid: The call to update.
+            data: Pipeline update payload.
+        """
+        return await self.update(call_sid, {"pipeline_update": data})
+
+    async def noise_isolation(
+        self, call_sid: str, status: str, opts: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Enable or disable noise isolation.
+
+        Args:
+            call_sid: The call.
+            status: ``'on'`` or ``'off'``.
+            opts: Additional noise isolation options.
+        """
+        data: dict[str, Any] = {"noiseIsolation_status": status}
+        if opts:
+            data.update(opts)
+        return await self.update(call_sid, data)
+
+
+class ConferencesResource(_Resource):
+    """REST API operations for conferences."""
+
+    def __init__(self, client: JambonzClient) -> None:
+        super().__init__(client, "/Conferences")
+
+    async def list(self) -> list[dict[str, Any]]:
+        """List active conferences."""
+        return await self._request("GET")
+
+
+class QueuesResource(_Resource):
+    """REST API operations for call queues."""
+
+    def __init__(self, client: JambonzClient) -> None:
+        super().__init__(client, "/Queues")
+
+    async def list(self, search: str | None = None) -> list[dict[str, Any]]:
+        """List active queues.
+
+        Args:
+            search: Optional search string to filter queues.
+        """
+        params = {"search": search} if search else None
+        return await self._request("GET", params=params)
+
+
+class JambonzClient:
+    """REST API client for jambonz platform.
+
+    Provides access to call control, conferences, and queues.
+
+    Example::
+
+        client = JambonzClient(
+            base_url="https://api.jambonz.us",
+            account_sid="your-account-sid",
+            api_key="your-api-key",
+        )
+
+        # Create an outbound call
+        call_sid = await client.calls.create({
+            "from": "+15085551212",
+            "to": {"type": "phone", "number": "+15085551213"},
+            "call_hook": "/incoming",
+        })
+
+        # Mid-call control
+        await client.calls.mute(call_sid, "mute")
+        await client.calls.whisper(call_sid, {"verb": "say", "text": "Hello"})
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        account_sid: str,
+        api_key: str,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._account_sid = account_sid
+        self._api_key = api_key
+        self._session: aiohttp.ClientSession | None = None
+
+        # Resource accessors
+        self.calls = CallsResource(self)
+        self.conferences = ConferencesResource(self)
+        self.queues = QueuesResource(self)
+
+    @property
+    def _api_base(self) -> str:
+        return f"{self._base_url}/v1/Accounts/{self._account_sid}"
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "Content-Type": "application/json",
+                }
+            )
+        return self._session
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, str] | None = None,
+    ) -> Any:
+        session = await self._get_session()
+        url = f"{self._api_base}{path}"
+
+        async with session.request(method, url, json=json, params=params) as resp:
+            if resp.status == 204:
+                return None
+            resp.raise_for_status()
+            if resp.content_type == "application/json":
+                return await resp.json()
+            return await resp.text()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def __aenter__(self) -> JambonzClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

jambonz_sdk/schema/callbacks/amd.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/amd",
+  "title": "AMD ActionHook Payload",
+  "description": "Payload sent to the AMD actionHook when an answering machine detection event occurs. Multiple events may fire during a single call (e.g. amd_machine_detected followed by amd_machine_stopped_speaking or amd_tone_detected).",
+  "allOf": [{ "$ref": "base" }],
+  "type": "object",
+  "properties": {
+    "type": {
+      "type": "string",
+      "description": "The AMD event type. IMPORTANT: This field is 'type', NOT 'amd_type'.",
+      "enum": [
+        "amd_human_detected",
+        "amd_machine_detected",
+        "amd_no_speech_detected",
+        "amd_decision_timeout",
+        "amd_machine_stopped_speaking",
+        "amd_tone_detected",
+        "amd_tone_timeout",
+        "amd_error",
+        "amd_stopped"
+      ]
+    },
+    "reason": {
+      "type": "string",
+      "description": "Reason for the detection result (e.g. 'short greeting', 'long greeting', 'hint', 'digit count'). Present on amd_human_detected and amd_machine_detected events."
+    },
+    "greeting": {
+      "type": "string",
+      "description": "The transcribed greeting text. Present on amd_human_detected and amd_machine_detected events."
+    },
+    "hint": {
+      "type": "string",
+      "description": "The voicemail hint that matched, if detection was triggered by hint matching."
+    },
+    "language": {
+      "type": "string",
+      "description": "Language code from the transcription (e.g. 'en-US'). Present on amd_human_detected and amd_machine_detected events."
+    },
+    "frequency": {
+      "type": "number",
+      "description": "Frequency of the detected beep in Hz. Present on amd_tone_detected events."
+    },
+    "variance": {
+      "type": "number",
+      "description": "Frequency variance of the detected beep. Present on amd_tone_detected events."
+    }
+  },
+  "required": ["type"]
+}

jambonz_sdk/schema/callbacks/base.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/base",
+  "title": "ActionHook Base Payload",
+  "description": "Common fields present in every actionHook callback payload. All verb-specific callback schemas extend this base.",
+  "type": "object",
+  "properties": {
+    "call_sid": { "type": "string", "description": "Unique identifier for this call." },
+    "account_sid": { "type": "string", "description": "Account identifier." },
+    "application_sid": { "type": "string", "description": "Application identifier." },
+    "direction": { "type": "string", "enum": ["inbound", "outbound"], "description": "Call direction." },
+    "from": { "type": "string", "description": "Caller phone number or SIP URI." },
+    "to": { "type": "string", "description": "Called phone number or SIP URI." },
+    "call_id": { "type": "string", "description": "SIP Call-ID." },
+    "sbc_callid": { "type": "string", "description": "SBC-level Call-ID." },
+    "call_status": {
+      "type": "string",
+      "enum": ["trying", "ringing", "early-media", "in-progress", "completed", "failed", "busy", "no-answer", "queued"],
+      "description": "Current call state."
+    },
+    "sip_status": { "type": "integer", "description": "SIP response code (e.g. 200, 486)." },
+    "sip_reason": { "type": "string", "description": "SIP reason phrase (e.g. 'OK', 'Busy Here')." },
+    "trace_id": { "type": "string", "description": "Distributed tracing identifier for correlating logs across jambonz components." },
+    "originating_sip_ip": { "type": "string", "description": "IP address of the originating SIP trunk." },
+    "originating_sip_trunk_name": { "type": "string", "description": "Name of the originating SIP trunk as configured in jambonz." },
+    "api_base_url": { "type": "string", "description": "jambonz REST API base URL. Use this for mid-call control via the REST API." }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/call-status",
+  "title": "Call Status Webhook Payload",
+  "description": "Payload sent to the call status webhook URL whenever the call state changes (e.g. trying, in-progress, completed). The status webhook is configured at the application level in jambonz. Multiple status events are sent over the life of a call. The final event (completed or failed) includes additional fields like duration and termination cause.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "call_termination_by": {
+      "type": "string",
+      "enum": ["caller", "jambonz"],
+      "description": "Who terminated the call. 'caller' if the remote party hung up, 'jambonz' if the call was ended by the application (e.g. hangup verb, REST API). Present only on the final status event (completed/failed)."
+    },
+    "duration": {
+      "type": "integer",
+      "description": "Call duration in seconds. Present only on the final status event (completed/failed)."
+    }
+  },
+  "additionalProperties": true
+}

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/conference-status",
+  "title": "Conference StatusHook Payload",
+  "description": "Payload sent to the conference statusHook when a conference event occurs.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "event": {
+      "type": "string",
+      "enum": ["start", "end", "join", "leave", "start-talking", "stop-talking"],
+      "description": "The conference event that occurred."
+    },
+    "conference_sid": { "type": "string", "description": "Conference identifier (format: conf:<account_sid>:<conference_name>)." },
+    "friendly_name": { "type": "string", "description": "The conference name as specified in the conference verb." },
+    "duration": { "type": "number", "description": "Time in seconds since the conference started." },
+    "members": { "type": "integer", "description": "Current number of participants in the conference." },
+    "time": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the event occurred." }
+  },
+  "required": ["event", "conference_sid"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/conference-wait.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/conference-wait",
+  "title": "Conference WaitHook Payload",
+  "description": "Payload sent to the conference waitHook while a participant is waiting for the conference to start. The response should contain an array of say, play, and/or pause verbs to play while waiting.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/conference.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/conference",
+  "title": "Conference ActionHook Payload",
+  "description": "Payload sent to the conference verb's actionHook when the participant leaves or the conference ends. Contains only the base call info.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/dequeue.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dequeue",
+  "title": "Dequeue ActionHook Payload",
+  "description": "Payload sent to the dequeue verb's actionHook when the dequeue operation completes.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "dequeue_result": {
+      "type": "string",
+      "enum": ["complete", "timeout", "hangup"],
+      "description": "Outcome of the dequeue. 'complete' — successfully dequeued and bridged; 'timeout' — no queued caller found; 'hangup' — call hung up during bridge."
+    }
+  },
+  "required": ["dequeue_result"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/dial-dtmf.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dial-dtmf",
+  "title": "Dial DtmfHook Payload",
+  "description": "Payload sent to the dial dtmfHook when DTMF digits matching the configured pattern are detected during a dial.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "dtmf": {
+      "type": "string",
+      "description": "The DTMF digit sequence that matched the configured dtmfCapture pattern."
+    }
+  },
+  "required": ["dtmf"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/dial-hold.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dial-hold",
+  "title": "Dial OnHoldHook Payload",
+  "description": "Payload sent to the dial onHoldHook when the remote party places the call on hold. The response should contain say, play, and/or pause verbs to play as hold music. The hook is called repeatedly until the hold ends.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "hold_detail": {
+      "type": "object",
+      "description": "Details of the hold event.",
+      "properties": {
+        "from": { "type": "string", "description": "SIP From header value." },
+        "to": { "type": "string", "description": "SIP To header value." }
+      }
+    }
+  },
+  "required": ["hold_detail"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/dial-refer.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dial-refer",
+  "title": "Dial ReferHook Payload",
+  "description": "Payload sent to the dial referHook when a SIP REFER is received during an active dial. The response can contain new verbs to execute.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "refer_details": {
+      "type": "object",
+      "description": "Details of the SIP REFER request. Any custom X-* headers on the REFER are also included as snake_cased properties (e.g. X-Override-Number becomes x_override_number).",
+      "properties": {
+        "sip_refer_to": { "type": "string", "description": "Full SIP Refer-To header value." },
+        "refer_to_user": { "type": "string", "description": "User part of the Refer-To URI (phone number or SIP user)." },
+        "sip_referred_by": { "type": "string", "description": "SIP Referred-By header value, if present." },
+        "referred_by_user": { "type": "string", "description": "User part of the Referred-By URI, if present." },
+        "sip_user_agent": { "type": "string", "description": "User-Agent header from the REFER request." },
+        "referring_call_sid": { "type": "string", "description": "Call SID of the leg that sent the REFER." },
+        "referred_call_sid": { "type": "string", "description": "Call SID of the leg being referred." }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": ["refer_details"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/dial.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/dial",
+  "title": "Dial ActionHook Payload",
+  "description": "Payload sent to the actionHook when a dial verb completes, either because the dialed party hung up, the call was not answered, or an error occurred.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "dial_call_status": {
+      "type": "string",
+      "enum": ["completed", "failed", "busy", "no-answer", "trying", "ringing", "early-media", "in-progress"],
+      "description": "Final status of the outbound (dialed) call leg."
+    },
+    "dial_sip_status": {
+      "type": "integer",
+      "description": "SIP response code from the dialed party (e.g. 200, 486, 487).",
+      "examples": [200, 486, 487]
+    },
+    "dial_call_sid": {
+      "type": "string",
+      "description": "Call SID of the outbound (dialed) call leg."
+    },
+    "dial_sbc_callid": {
+      "type": "string",
+      "description": "SBC-level Call-ID for the outbound (dialed) call leg."
+    }
+  },
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/enqueue-wait.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/enqueue-wait",
+  "title": "Enqueue WaitHook Payload",
+  "description": "Payload sent to the enqueue waitHook while a caller is waiting in the queue. The response should contain an array of say, play, pause, and/or leave verbs. Note: this payload is sparse — it contains queue-specific fields plus call_sid and call_id, but NOT the full base payload fields.",
+  "type": "object",
+  "properties": {
+    "queue_sid": { "type": "string", "description": "Queue identifier in the format 'queue:{account_sid}:{queue_name}'." },
+    "queue_time": { "type": "integer", "description": "Time in seconds the caller has been waiting in the queue." },
+    "queue_size": { "type": "integer", "description": "Total number of callers currently in the queue." },
+    "queue_position": { "type": "integer", "description": "Caller's current position in the queue (0-based)." },
+    "call_sid": { "type": "string", "description": "Unique identifier for this call." },
+    "call_id": { "type": "string", "description": "SIP Call-ID." }
+  },
+  "required": ["queue_sid", "queue_time"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/enqueue.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/enqueue",
+  "title": "Enqueue ActionHook Payload",
+  "description": "Payload sent to the enqueue actionHook when the enqueue verb completes — i.e. the call was bridged, abandoned, left the queue, or an error occurred.",
+  "allOf": [
+    { "$ref": "base" }
+  ],
+  "type": "object",
+  "properties": {
+    "queue_sid": {
+      "type": "string",
+      "description": "Queue identifier in the format 'queue:{account_sid}:{queue_name}'."
+    },
+    "queue_time": {
+      "type": "integer",
+      "description": "Time in seconds the caller spent waiting in the queue."
+    },
+    "queue_result": {
+      "type": "string",
+      "enum": ["bridged", "hangup", "leave", "error"],
+      "description": "Outcome of the enqueue. 'bridged' — call was dequeued and connected; 'hangup' — caller hung up while waiting; 'leave' — caller executed a leave verb from the waitHook; 'error' — an error occurred during bridging."
+    }
+  },
+  "required": ["queue_sid", "queue_time", "queue_result"],
+  "additionalProperties": true
+}

jambonz_sdk/schema/callbacks/gather-partial.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jambonz.org/schema/callbacks/gather-partial",
+  "title": "Gather Partial Transcript Payload",
+  "description": "Payload sent to the partialResultHook during a gather verb with speech input. Delivers interim (partial) speech recognition results as they arrive, before the gather completes. This hook is informational — the response is ignored and does not replace the verb stack. Note: the base fields use slightly different names than the actionHook payload (e.g. local_sip_address instead of fs_sip_address).",
+  "type": "object",
+  "properties": {
+    "call_sid": { "type": "string", "description": "Unique identifier for this call." },
+    "account_sid": { "type": "string", "description": "Account identifier." },
+    "application_sid": { "type": "string", "description": "Application identifier." },
+    "direction": { "type": "string", "enum": ["inbound", "outbound"], "description": "Call direction." },
+    "from": { "type": "string", "description": "Caller phone number or SIP URI." },
+    "to": { "type": "string", "description": "Called phone number or SIP URI." },
+    "call_id": { "type": "string", "description": "SIP Call-ID." },
+    "sbc_callid": { "type": "string", "description": "SBC-level Call-ID." },
+    "call_status": { "type": "string", "description": "Current call state." },
+    "sip_status": { "type": "integer", "description": "SIP response code." },
+    "sip_reason": { "type": "string", "description": "SIP reason phrase." },
+    "trace_id": { "type": "string", "description": "Distributed tracing identifier." },
+    "b3": { "type": "string", "description": "B3 trace propagation header." },
+    "caller_name": { "type": "string", "description": "Caller display name from SIP, if available." },
+    "originating_sip_ip": { "type": "string", "description": "IP address of the originating SIP trunk." },
+    "originating_sip_trunk_name": { "type": "string", "description": "Name of the originating SIP trunk." },
+    "speech": {
+      "type": "object",
+      "description": "Interim speech recognition results.",
+      "properties": {
+        "language_code": { "type": "string", "description": "Language code used for recognition (e.g. 'en-US')." },
+        "channel_tag": { "type": "integer", "description": "Audio channel number." },
+        "is_final": { "type": "boolean", "description": "Always false for partial results." },
+        "alternatives": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "transcript": { "type": "string", "description": "The partial transcript recognized so far." },
+              "confidence": { "type": "number", "description": "Confidence score between 0 and 1." }
+            }
+          },
+          "description": "Array of recognition alternatives, ordered by confidence."
+        },
+        "vendor": {
+          "type": "object",
+          "description": "Vendor-specific STT data. Structure varies by provider.",
+          "properties": {
+            "name": { "type": "string", "description": "STT vendor name (e.g. 'deepgram', 'google', 'aws')." },
+            "evt": { "type": "object", "description": "Raw vendor-specific event payload.", "additionalProperties": true }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}