jaxl-python 0.0.38__tar.gz → 0.0.39__tar.gz

{jaxl_python-0.0.38 → jaxl_python-0.0.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jaxl-python
-Version: 0.0.38
+Version: 0.0.39
 Summary: Official Python SDK and CLI for interfacing with the Jaxl API. Manage calls, messages, IVRs, devices, teams, payments, campaigns, streaming transcriptions and AI Agents. Built on OpenAPI, it offers both generated API clients and Pythonic wrappers for ease of use.
 Home-page: https://github.com/jaxl-innovations-private-limited/jaxl-python
 Download-URL: https://github.com/jaxl-innovations-private-limited/jaxl-python/archive/main.zip

{jaxl_python-0.0.38 → jaxl_python-0.0.39}/examples/__init__.py

@@ -16,6 +16,7 @@ from .streaming_aiagent import JaxlAppStreamingAIAgent
 from .streaming_audio_chunks import JaxlAppStreamingAudioChunk
 from .streaming_speech_segments import JaxlAppStreamingSpeechSegment
 from .streaming_transcriptions import JaxlAppStreamingTranscription
+from .streaming_wav_file import JaxlAppStreamingWavFile
 
 
 __all__ = [
@@ -26,4 +27,5 @@ __all__ = [
     "JaxlAppStreamingSpeechSegment",
     "JaxlAppStreamingTranscription",
     "JaxlAppStreamingAIAgent",
+    "JaxlAppStreamingWavFile",
 ]

jaxl_python-0.0.39/examples/streaming_wav_file.py

@@ -0,0 +1,95 @@
+"""
+Copyright (c) 2010-present by Jaxl Innovations Private Limited.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms,
+with or without modification, is strictly prohibited.
+"""
+
+import asyncio
+# pylint: disable=deprecated-module
+import audioop
+import os
+import wave
+from pathlib import Path
+from typing import Dict
+
+from jaxl.api.base import (
+    HANDLER_RESPONSE,
+    BaseJaxlApp,
+    JaxlWebhookRequest,
+    JaxlWebhookResponse,
+)
+
+
+SAMPLE_RATE = 8000
+SAMPLE_WIDTH = 2
+CHANNELS = 1
+FRAME_MS = 20
+FRAME_BYTES = SAMPLE_RATE * SAMPLE_WIDTH * FRAME_MS // 1000
+SEND_INTERVAL_S = 0.010  # Send faster than real-time to avoid SIP jitter.
+
+
+def load_wav_as_slin16_8k_mono(path: str) -> bytes:
+    with wave.open(path, "rb") as wav:
+        audio = wav.readframes(wav.getnframes())
+        sample_width = wav.getsampwidth()
+        channels = wav.getnchannels()
+        sample_rate = wav.getframerate()
+
+    if channels != CHANNELS:
+        audio = audioop.tomono(audio, sample_width, 0.5, 0.5)
+        channels = CHANNELS
+    if sample_width != SAMPLE_WIDTH:
+        audio = audioop.lin2lin(audio, sample_width, SAMPLE_WIDTH)
+        sample_width = SAMPLE_WIDTH
+    if sample_rate != SAMPLE_RATE:
+        audio, _ = audioop.ratecv(
+            audio,
+            sample_width,
+            channels,
+            sample_rate,
+            SAMPLE_RATE,
+            None,
+        )
+    return audio
+
+
+class JaxlAppStreamingWavFile(BaseJaxlApp):
+    """Minimal incoming-call app that streams one WAV file over the live stream."""
+
+    def __init__(self) -> None:
+        self._playback_tasks: Dict[int, asyncio.Task[None]] = {}
+        self._wav_path = os.environ.get("JAXL_STREAMING_WAV_PATH", "example.wav")
+        self._audio = load_wav_as_slin16_8k_mono(self._wav_path)
+
+    async def handle_setup(self, req: JaxlWebhookRequest) -> HANDLER_RESPONSE:
+        return JaxlWebhookResponse(prompt=[], num_characters=-1)
+
+    async def handle_teardown(self, req: JaxlWebhookRequest) -> HANDLER_RESPONSE:
+        assert req.state is not None
+        self._cancel_playback(req.state.call_id)
+        return None
+
+    async def on_stream_connect(self, call_id: int) -> None:
+        self._cancel_playback(call_id)
+        self._playback_tasks[call_id] = asyncio.create_task(self._stream_wav(call_id))
+
+    async def on_stream_disconnect(self, call_id: int) -> None:
+        self._cancel_playback(call_id)
+
+    def _cancel_playback(self, call_id: int) -> None:
+        task = self._playback_tasks.pop(call_id, None)
+        if task is not None:
+            task.cancel()
+
+    async def _stream_wav(self, call_id: int) -> None:
+        print(f"Streaming {Path(self._wav_path)} to call {call_id}")
+        for offset in range(0, len(self._audio), FRAME_BYTES):
+            chunk = self._audio[offset : offset + FRAME_BYTES]
+            if len(chunk) < FRAME_BYTES:
+                chunk += b"\x00" * (FRAME_BYTES - len(chunk))
+            if not await self.send_audio(call_id, chunk):
+                break
+            await asyncio.sleep(SEND_INTERVAL_S)

{jaxl_python-0.0.38 → jaxl_python-0.0.39}/jaxl/api/client/_scm_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.0.38'
-__version_tuple__ = version_tuple = (0, 0, 38)
+__version__ = version = '0.0.39'
+__version_tuple__ = version_tuple = (0, 0, 39)

{jaxl_python-0.0.38 → jaxl_python-0.0.39}/jaxl/api/resources/apps.py

@@ -20,8 +20,7 @@ import tempfile
 import uuid
 import warnings
 import wave
-from collections import deque
-from typing import TYPE_CHECKING, Any, Deque, Dict, List, Optional, cast
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, cast
 
 from fastapi.websockets import WebSocketState
 from starlette.websockets import WebSocketDisconnect
@@ -37,7 +36,7 @@ from jaxl.api.base import (
 from jaxl.api.client.models.call_tag_response import CallTagResponse
 from jaxl.api.client.types import Response
 from jaxl.api.resources.accounts import accounts_me
-from jaxl.api.resources.calls import calls_hangup, calls_tag_add
+from jaxl.api.resources.calls import calls_ahangup, calls_atag_add
 from jaxl.api.resources.silence import SilenceDetector
 
 
@@ -138,10 +137,10 @@ def _start_server(
     wss: Dict[int, WebSocket] = {}
 
     async def _add_tag(call_id: int, tag: str) -> Response[CallTagResponse]:
-        return calls_tag_add({"call_id": call_id, "tag": tag})
+        return await calls_atag_add({"call_id": call_id, "tag": tag})
 
     async def _hangup(call_id: int) -> Response[Any]:
-        return calls_hangup({"call_id": call_id})
+        return await calls_ahangup({"call_id": call_id})
 
     async def _clear_audio(call_id: int) -> bool:
         try:
@@ -239,7 +238,6 @@ def _start_server(
             speech_frame_threshold=vad_speech_frame_threshold,
         )
         speaking: bool = False
-        buffer: Deque[bytes] = deque(maxlen=4)
         slin16s: List[bytes] = []
 
         await ws.accept()
@@ -257,18 +255,22 @@ def _start_server(
                     # Invoke audio chunk handlers
                     await app.handle_audio_chunk(req, slin16)
                     # Detect start/end of speech
-                    buffer.append(slin16)
                     change = sdetector.process(slin16)
-                    current_frame_is_speech = sdetector.last_frame_is_speech
                     # Manage speech segments
                     if change is True:
                         speaking = change
                         await app.handle_speech_detection(state["call_id"], speaking)
-                        if len(slin16s) == 0:
-                            # Copy over a short, fixed preroll window.
-                            slin16s = list(buffer)
-                            if len(slin16s) > 0:
-                                await app.handle_speech_chunks(req, slin16s)
+                        # Pull the detector's preroll — this contains the
+                        # trigger frames (the `speech_frame_threshold` speech
+                        # frames that fired speech-start) plus a few earlier
+                        # frames for consonant-onset context. Forwarding
+                        # this preroll fixes the head-clipping bug where
+                        # short utterances ("haan", "ji") were truncated.
+                        preroll_bytes = sdetector.consume_preroll()
+                        if preroll_bytes:
+                            preroll_chunks = [preroll_bytes]
+                            slin16s.extend(preroll_chunks)
+                            await app.handle_speech_chunks(req, preroll_chunks)
                     elif change is False:
                         speaking = change
                         await app.handle_speech_detection(state["call_id"], speaking)
@@ -290,9 +292,14 @@ def _start_server(
                     else:
                         assert change is None
                         if speaking is True:
-                            if current_frame_is_speech:
-                                await app.handle_speech_chunks(req, [slin16])
-                                slin16s.append(slin16)
+                            # Forward EVERY chunk during an active speech
+                            # segment — including frames webrtcvad flagged
+                            # as not-speech. Inter-word silences (e.g.
+                            # between "haan" and "maam") are part of the
+                            # utterance and dropping them corrupts prosody
+                            # and confuses downstream ASR.
+                            await app.handle_speech_chunks(req, [slin16])
+                            slin16s.append(slin16)
                         else:
                             assert speaking is False
                 elif ev == "connected":

{jaxl_python-0.0.38 → jaxl_python-0.0.39}/jaxl/api/resources/calls.py

@@ -274,6 +274,18 @@ def calls_tag_add(args: Dict[str, Any]) -> Response[CallTagResponse]:
     )
 
 
+async def calls_atag_add(args: Dict[str, Any]) -> Response[CallTagResponse]:
+    return await v1_calls_tags_create.asyncio_detailed(
+        call_id=args["call_id"],
+        client=jaxl_api_client(
+            JaxlApiModule.CALL,
+            credentials=args.get("credentials", None),
+            auth_token=args.get("auth_token", None),
+        ),
+        json_body=CallTagRequest(name=args["tag"]),
+    )
+
+
 def calls_hangup(args: Dict[str, Any]) -> Response[Any]:
     return v1_calls_hangup_retrieve.sync_detailed(
         id=args["call_id"],
@@ -285,6 +297,17 @@ def calls_hangup(args: Dict[str, Any]) -> Response[Any]:
     )
 
 
+async def calls_ahangup(args: Dict[str, Any]) -> Response[Any]:
+    return await v1_calls_hangup_retrieve.asyncio_detailed(
+        id=args["call_id"],
+        client=jaxl_api_client(
+            JaxlApiModule.CALL,
+            credentials=args.get("credentials", None),
+            auth_token=args.get("auth_token", None),
+        ),
+    )
+
+
 def calls_transfer(args: Dict[str, Any]) -> Response[Any]:
     return v1_calls_transfer_create.sync_detailed(
         id=args["call_id"],
@@ -321,6 +344,30 @@ def calls_message(args: Dict[str, Any]) -> Response[Any]:
     )
 
 
+async def calls_amessage(args: Dict[str, Any]) -> Response[Any]:
+    return await v1_calls_messages_create.asyncio_detailed(
+        id=args["call_id"],
+        client=jaxl_api_client(
+            JaxlApiModule.CALL,
+            credentials=args.get("credentials", None),
+            auth_token=args.get("auth_token", None),
+        ),
+        json_body=CallMessageRequestRequest(
+            text=encrypt(args["text"]),
+            timestamp=datetime.fromtimestamp(
+                args.get("epoch", None) or time.time(),
+                tz=timezone.utc,
+            ),
+            why=WhyEnum[cast(str, args["direction"]).upper()],
+            type=(
+                CallMessageRequestTypeEnum.VALUE_1
+                if args["type"] == "chat"
+                else CallMessageRequestTypeEnum.VALUE_10
+            ),
+        ),
+    )
+
+
 def calls_audio(args: Dict[str, Any]) -> Response[Any | CallAudioReason]:
     assert "call_id" in args and "path" in args
     response = v1_calls_audio_retrieve.sync_detailed(
@@ -611,11 +658,20 @@ class JaxlCallsSDK:
     def add_tag(self, **kwargs: Any) -> Response[CallTagResponse]:
         return calls_tag_add(kwargs)
 
+    async def aadd_tag(self, **kwargs: Any) -> Response[CallTagResponse]:
+        return await calls_atag_add(kwargs)
+
     def hangup(self, **kwargs: Any) -> Response[Any]:
         return calls_hangup(kwargs)
 
+    async def ahangup(self, **kwargs: Any) -> Response[Any]:
+        return await calls_ahangup(kwargs)
+
     def message(self, **kwargs: Any) -> Response[Any]:
         return calls_message(kwargs)
 
+    async def amessage(self, **kwargs: Any) -> Response[Any]:
+        return await calls_amessage(kwargs)
+
     def audio(self, **kwargs: Any) -> Response[Any | CallAudioReason]:
         return calls_audio(kwargs)

jaxl_python-0.0.39/jaxl/api/resources/silence.py

@@ -0,0 +1,151 @@
+"""
+Copyright (c) 2010-present by Jaxl Innovations Private Limited.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms,
+with or without modification, is strictly prohibited.
+"""
+
+from collections import deque
+from typing import Deque, Optional
+
+
+# pylint: disable=too-many-instance-attributes
+class SilenceDetector:
+    """Edge-triggered VAD wrapper around py-webrtcvad.
+
+    Streaming contract: feed PCM16 mono audio one chunk at a time via
+    ``process()``. The method returns:
+
+    - ``True`` once on the speech-start edge
+    - ``False`` once on the speech-end edge
+    - ``None`` while no edge has been detected on this call
+
+    Preroll buffer (FIX for head clipping)
+    --------------------------------------
+    By design, ``speech_frame_threshold`` consecutive speech frames must
+    elapse before the detector declares speech-start. Those trigger
+    frames carry the actual onset of the user's utterance (e.g. the "h"
+    in "haan") and previously had no public surface for callers to
+    recover them — at best the caller kept a tiny rolling preroll that
+    was smaller than the trigger window, and the very first speech frame
+    was always lost.
+
+    The detector now maintains its own ``preroll`` deque that captures
+    every processed frame. When speech-start fires, the caller MUST call
+    ``consume_preroll()`` to retrieve those frames and prepend them to
+    the audio it forwards to ASR. ``consume_preroll`` returns the bytes
+    AND clears the buffer, so subsequent calls within the same speech
+    segment are safe (return empty).
+
+    The preroll size is configurable but defaults to a slightly larger
+    window than ``speech_frame_threshold`` so the caller also receives a
+    small amount of audio captured just BEFORE the trigger window — this
+    catches consonant onsets that webrtcvad sometimes fails to flag as
+    speech (e.g. "h", "f", "s") but still belong to the utterance.
+    """
+
+    # pylint: disable=too-many-positional-arguments
+    def __init__(
+        self,
+        sample_rate: int = 8000,
+        frame_duration_ms: int = 20,
+        aggressiveness: int = 2,
+        silence_frame_threshold: int = 12,  # ~240ms
+        speech_frame_threshold: int = 5,  # ~100ms
+        preroll_frames: Optional[int] = None,
+    ):
+        import webrtcvad
+
+        self.sample_rate = sample_rate
+        self.frame_duration_ms = frame_duration_ms
+        self.aggressiveness = aggressiveness
+        self.frame_size = int(self.sample_rate * self.frame_duration_ms / 1000)
+        self.vad = webrtcvad.Vad(self.aggressiveness)
+
+        self.speech_frame_threshold = speech_frame_threshold
+        self.silence_frame_threshold = silence_frame_threshold
+
+        # Preroll covers AT LEAST the trigger window plus a few extra frames
+        # of pre-trigger audio, so the caller never sees a truncated onset.
+        # Five extra frames (~100ms) is enough to recover voiceless
+        # consonants that VAD initially missed while keeping memory tiny.
+        if preroll_frames is None:
+            preroll_frames = speech_frame_threshold + 5
+
+        self.is_talking = False
+        self.speech_frames = 0
+        self.silence_frames = 0
+        self.buffer = b""
+        self.last_frame_is_speech: Optional[bool] = None
+        self._preroll: Deque[bytes] = deque(maxlen=preroll_frames)
+
+    def process(self, slin16: bytes) -> Optional[bool]:
+        """Process PCM16 mono audio. Returns:
+        - True once on speech start
+        - False once on speech end
+        - None if no change
+
+        Side-effect: every fully formed frame is appended to the preroll
+        buffer. On the speech-start edge the caller should call
+        ``consume_preroll()`` to retrieve the trigger frames.
+        """
+        self.buffer += slin16
+        change = None
+
+        while len(self.buffer) >= self.frame_size * 2:
+            frame, self.buffer = (
+                self.buffer[: self.frame_size * 2],
+                self.buffer[self.frame_size * 2 :],
+            )
+
+            # Always preserve the frame in the preroll. Bounded by maxlen,
+            # so memory is O(preroll_frames) regardless of call duration.
+            self._preroll.append(frame)
+
+            is_speech = self.vad.is_speech(frame, self.sample_rate)
+            self.last_frame_is_speech = is_speech
+
+            if is_speech:
+                self.speech_frames += 1
+                self.silence_frames = 0
+                if (
+                    not self.is_talking
+                    and self.speech_frames >= self.speech_frame_threshold
+                ):
+                    change = True  # silence -> speech
+                    self.is_talking = True
+            else:
+                self.silence_frames += 1
+                self.speech_frames = 0
+                if (
+                    self.is_talking
+                    and self.silence_frames >= self.silence_frame_threshold
+                ):
+                    change = False  # speech -> silence
+                    self.is_talking = False
+
+        return change
+
+    def consume_preroll(self) -> bytes:
+        """Return the preroll buffer as concatenated PCM16 bytes and clear it.
+
+        Call this immediately after ``process()`` returns ``True`` (the
+        speech-start edge). The returned bytes contain the frames that
+        triggered the start plus a few preceding frames for context, and
+        should be prepended to the audio stream forwarded to ASR.
+
+        Subsequent calls within the same speech segment return ``b""``.
+        """
+        out = b"".join(self._preroll)
+        self._preroll.clear()
+        return out
+
+    def reset(self) -> None:
+        self.buffer = b""
+        self.silence_frames = 0
+        self.speech_frames = 0
+        self.is_talking = False
+        self.last_frame_is_speech = None
+        self._preroll.clear()

{jaxl_python-0.0.38 → jaxl_python-0.0.39}/jaxl_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jaxl-python
-Version: 0.0.38
+Version: 0.0.39
 Summary: Official Python SDK and CLI for interfacing with the Jaxl API. Manage calls, messages, IVRs, devices, teams, payments, campaigns, streaming transcriptions and AI Agents. Built on OpenAPI, it offers both generated API clients and Pythonic wrappers for ease of use.
 Home-page: https://github.com/jaxl-innovations-private-limited/jaxl-python
 Download-URL: https://github.com/jaxl-innovations-private-limited/jaxl-python/archive/main.zip

{jaxl_python-0.0.38 → jaxl_python-0.0.39}/jaxl_python.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ examples/streaming_aiagent.py
 examples/streaming_audio_chunks.py
 examples/streaming_speech_segments.py
 examples/streaming_transcriptions.py
+examples/streaming_wav_file.py
 examples/prompts/example.txt
 jaxl/api/__init__.py
 jaxl/api/_client.py

{jaxl_python-0.0.38 → jaxl_python-0.0.39}/tests/test_streaming_vad.py

@@ -73,6 +73,11 @@ class StreamingVadTest(unittest.TestCase):
         self.assertTrue(change)
 
     def test_streaming_vad_preserves_preroll_with_earlier_speech_start(self) -> None:
+        """When speech-start fires the pipeline must forward at least the
+        speech_frame_threshold trigger frames. Previously a rolling
+        deque(maxlen=4) clipped the very first speech frame; the silence
+        detector now exposes its own preroll covering ALL trigger frames.
+        """
         app = _StreamingCaptureApp()
         server = _start_server(app, vad_speech_frame_threshold=5)
         state = {
@@ -103,9 +108,19 @@ class StreamingVadTest(unittest.TestCase):
 
         self.assertEqual(app.speech_detection_events[:2], [True, False])
         self.assertGreaterEqual(len(app.speech_chunk_batches), 1)
-        self.assertEqual(len(app.speech_chunk_batches[0]), 4)
+        # The first batch is the silence detector's preroll (concatenated
+        # PCM16 bytes covering all 5 trigger frames). It is delivered as a
+        # single bytes-list entry rather than per-frame, but must contain
+        # ALL 5 trigger frames worth of audio.
+        first_batch = app.speech_chunk_batches[0]
+        first_batch_bytes = b"".join(first_batch)
+        # 5 frames * 320 bytes/frame = 1600 bytes — the full trigger window.
+        self.assertGreaterEqual(len(first_batch_bytes), 5 * 320)
+        # Every byte in the preroll must come from the speech tone (0x01),
+        # not from earlier silence frames.
         self.assertTrue(
-            all(chunk == b"\x01" * 320 for chunk in app.speech_chunk_batches[0])
+            all(byte == 0x01 for byte in first_batch_bytes),
+            f"preroll contained non-speech bytes: {first_batch_bytes[:40]!r}",
         )
 
 

jaxl_python-0.0.38/jaxl/api/resources/silence.py

@@ -1,86 +0,0 @@
-"""
-Copyright (c) 2010-present by Jaxl Innovations Private Limited.
-
-All rights reserved.
-
-Redistribution and use in source and binary forms,
-with or without modification, is strictly prohibited.
-"""
-
-from typing import Optional
-
-
-# pylint: disable=too-many-instance-attributes
-class SilenceDetector:
-    """Edge-triggered VAD wrapper around py-webrtcvad."""
-
-    # pylint: disable=too-many-positional-arguments
-    def __init__(
-        self,
-        sample_rate: int = 8000,
-        frame_duration_ms: int = 20,
-        aggressiveness: int = 2,
-        silence_frame_threshold: int = 12,  # ~240ms
-        speech_frame_threshold: int = 5,  # ~100ms
-    ):
-        import webrtcvad
-
-        self.sample_rate = sample_rate
-        self.frame_duration_ms = frame_duration_ms
-        self.aggressiveness = aggressiveness
-        self.frame_size = int(self.sample_rate * self.frame_duration_ms / 1000)
-        self.vad = webrtcvad.Vad(self.aggressiveness)
-
-        self.speech_frame_threshold = speech_frame_threshold
-        self.silence_frame_threshold = silence_frame_threshold
-        self.is_talking = False
-        self.speech_frames = 0
-        self.silence_frames = 0
-        self.buffer = b""
-        self.last_frame_is_speech: Optional[bool] = None
-
-    def process(self, slin16: bytes) -> Optional[bool]:
-        """Process PCM16 mono audio. Returns:
-        - True once on speech start
-        - False once on speech end
-        - None if no change
-        """
-        self.buffer += slin16
-        change = None
-
-        while len(self.buffer) >= self.frame_size * 2:
-            frame, self.buffer = (
-                self.buffer[: self.frame_size * 2],
-                self.buffer[self.frame_size * 2 :],
-            )
-
-            is_speech = self.vad.is_speech(frame, self.sample_rate)
-            self.last_frame_is_speech = is_speech
-
-            if is_speech:
-                self.speech_frames += 1
-                self.silence_frames = 0
-                if (
-                    not self.is_talking
-                    and self.speech_frames >= self.speech_frame_threshold
-                ):
-                    change = True  # silence -> speech
-                    self.is_talking = True
-            else:
-                self.silence_frames += 1
-                self.speech_frames = 0
-                if (
-                    self.is_talking
-                    and self.silence_frames >= self.silence_frame_threshold
-                ):
-                    change = False  # speech -> silence
-                    self.is_talking = False
-
-        return change
-
-    def reset(self) -> None:
-        self.buffer = b""
-        self.silence_frames = 0
-        self.speech_frames = 0
-        self.is_talking = False
-        self.last_frame_is_speech = None