dominus-sdk-python-dev 2.4.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

dominus/namespaces/oracle/vad_gate.py

@@ -0,0 +1,276 @@
+"""
+VADGate - Voice Activity Detection Gate (INTERNAL)
+
+Implements a 4-state machine for VAD gating:
+IDLE -> ARMED -> SPEAKING -> TRAILING -> IDLE
+
+Features:
+- Pre-roll buffer (320ms) to capture word onsets
+- Armed confirmation (160ms) to reject false triggers
+- Post-roll/trailing (800ms) to avoid chopped endings
+- Circular buffer for pre-roll storage
+
+This module is INTERNAL and should NOT be exported publicly.
+"""
+
+import asyncio
+import struct
+import math
+from typing import List, Callable, Optional
+from dataclasses import dataclass
+
+from .types import VADState, ResolvedOracleSessionOptions
+
+
+@dataclass
+class VADGateConfig:
+    """Configuration for VADGate."""
+
+    # Number of frames in pre-roll buffer
+    preroll_frames: int
+
+    # Number of frames to confirm armed state
+    armed_confirm_frames: int
+
+    # Number of consecutive silence frames to confirm trailing (hysteresis)
+    silence_confirm_frames: int
+
+    # Post-roll timeout in ms
+    postroll_ms: int
+
+    # VAD threshold (0-1)
+    threshold: float
+
+    # Energy threshold for fallback VAD
+    energy_threshold: int
+
+
+def detect_speech_by_energy(pcm_frame: bytes, threshold: int = 500) -> bool:
+    """
+    Energy-based speech detection fallback.
+    Calculates RMS energy and compares against threshold.
+
+    Args:
+        pcm_frame: Raw PCM16 audio data
+        threshold: RMS energy threshold
+
+    Returns:
+        True if speech detected, False otherwise
+    """
+    # Convert bytes to int16 samples
+    num_samples = len(pcm_frame) // 2
+    if num_samples == 0:
+        return False
+
+    samples = struct.unpack(f"<{num_samples}h", pcm_frame)
+
+    # Calculate RMS energy
+    sum_squares = sum(s * s for s in samples)
+    rms = math.sqrt(sum_squares / num_samples)
+
+    return rms > threshold
+
+
+class EnergyVAD:
+    """
+    Energy-based VAD fallback.
+    Uses RMS energy detection when webrtcvad is unavailable.
+    """
+
+    def __init__(self, energy_threshold: int):
+        self.energy_threshold = energy_threshold
+
+    def is_speech(self, pcm_frame: bytes, _threshold: float) -> bool:
+        return detect_speech_by_energy(pcm_frame, self.energy_threshold)
+
+    def dispose(self) -> None:
+        pass
+
+
+class WebRTCVAD:
+    """
+    WebRTC VAD wrapper.
+    Falls back to energy-based detection if webrtcvad is unavailable.
+    """
+
+    def __init__(self, threshold: float, energy_threshold: int, sample_rate: int = 16000):
+        self.threshold = threshold
+        self.sample_rate = sample_rate
+        self.fallback = EnergyVAD(energy_threshold)
+        self.vad = None
+        self.use_fallback = False
+
+        try:
+            import webrtcvad
+            self.vad = webrtcvad.Vad()
+            # Aggressiveness level 0-3 (3 = most aggressive filtering)
+            # Map threshold (0-1) to aggressiveness (0-3)
+            aggressiveness = max(0, min(3, int((1 - threshold) * 3)))
+            self.vad.set_mode(aggressiveness)
+        except ImportError:
+            print("[OracleSDK] webrtcvad not available, using energy-based fallback")
+            self.use_fallback = True
+
+    def is_speech(self, pcm_frame: bytes, threshold: float) -> bool:
+        if self.use_fallback or self.vad is None:
+            return self.fallback.is_speech(pcm_frame, threshold)
+
+        try:
+            # webrtcvad requires specific frame sizes: 10, 20, or 30 ms
+            # For 16kHz, 20ms = 320 samples = 640 bytes
+            return self.vad.is_speech(pcm_frame, self.sample_rate)
+        except Exception:
+            # Fall back to energy-based on any error
+            return self.fallback.is_speech(pcm_frame, threshold)
+
+    def dispose(self) -> None:
+        self.vad = None
+
+
+class VADGate:
+    """
+    VADGate - 4-state Voice Activity Detection machine.
+
+    State transitions:
+    - IDLE -> ARMED: When VAD detects speech
+    - ARMED -> SPEAKING: After armed_confirm_frames of continuous speech
+    - ARMED -> IDLE: If speech stops before confirmation
+    - SPEAKING -> TRAILING: When VAD detects silence
+    - TRAILING -> SPEAKING: If speech resumes
+    - TRAILING -> IDLE: After postroll_ms timeout
+    """
+
+    def __init__(
+        self,
+        options: ResolvedOracleSessionOptions,
+        frame_duration_ms: int = 20,
+        loop: Optional[asyncio.AbstractEventLoop] = None
+    ):
+        self._state: VADState = "idle"
+        self._pre_roll_buffer: List[bytes] = []
+        self._armed_frame_count = 0
+        self._silence_frame_count = 0
+        self._trailing_task: Optional[asyncio.Task] = None
+        self._loop = loop
+
+        self._config = VADGateConfig(
+            preroll_frames=math.ceil(options.preroll_ms / frame_duration_ms),
+            armed_confirm_frames=math.ceil(options.armed_confirm_ms / frame_duration_ms),
+            silence_confirm_frames=8,  # 160ms of silence before trailing
+            postroll_ms=options.postroll_ms,
+            threshold=options.vad_threshold,
+            energy_threshold=options.energy_threshold,
+        )
+
+        # Use energy-based VAD as the primary implementation
+        self._vad_model = EnergyVAD(self._config.energy_threshold)
+
+        # Callbacks
+        self.on_send_audio: Optional[Callable[[List[bytes]], None]] = None
+        self.on_state_change: Optional[Callable[[VADState], None]] = None
+
+    @property
+    def state(self) -> VADState:
+        """Get current VAD state."""
+        return self._state
+
+    async def initialize(self) -> None:
+        """Initialize the VAD model (call before processing frames)."""
+        # Energy VAD doesn't need initialization
+        pass
+
+    def process_frame(self, pcm_frame: bytes) -> None:
+        """
+        Process an audio frame through the VAD gate.
+
+        Args:
+            pcm_frame: 20ms PCM16 audio frame (640 bytes)
+        """
+        # Maintain circular pre-roll buffer
+        self._pre_roll_buffer.append(pcm_frame)
+        if len(self._pre_roll_buffer) > self._config.preroll_frames:
+            self._pre_roll_buffer.pop(0)
+
+        is_speech = self._vad_model.is_speech(pcm_frame, self._config.threshold)
+
+        if self._state == "idle":
+            if is_speech:
+                self._set_state("armed")
+                self._armed_frame_count = 1
+
+        elif self._state == "armed":
+            if is_speech:
+                self._armed_frame_count += 1
+                if self._armed_frame_count >= self._config.armed_confirm_frames:
+                    # Confirmed speech - flush pre-roll buffer
+                    if self.on_send_audio:
+                        self.on_send_audio(list(self._pre_roll_buffer))
+                    self._set_state("speaking")
+            else:
+                # False trigger - back to idle
+                self._set_state("idle")
+                self._armed_frame_count = 0
+
+        elif self._state == "speaking":
+            if self.on_send_audio:
+                self.on_send_audio([pcm_frame])
+
+            if not is_speech:
+                # Hysteresis: require multiple consecutive silence frames
+                self._silence_frame_count += 1
+                if self._silence_frame_count >= self._config.silence_confirm_frames:
+                    self._set_state("trailing")
+                    self._start_trailing_timer()
+                    self._silence_frame_count = 0
+            else:
+                # Speech detected - reset silence counter
+                self._silence_frame_count = 0
+
+        elif self._state == "trailing":
+            if self.on_send_audio:
+                self.on_send_audio([pcm_frame])
+
+            if is_speech:
+                self._cancel_trailing_timer()
+                self._set_state("speaking")
+
+    def reset(self) -> None:
+        """Reset VAD state to idle."""
+        self._cancel_trailing_timer()
+        self._state = "idle"
+        self._pre_roll_buffer = []
+        self._armed_frame_count = 0
+        self._silence_frame_count = 0
+
+    def dispose(self) -> None:
+        """Clean up resources."""
+        self._cancel_trailing_timer()
+        self._vad_model.dispose()
+        self.on_send_audio = None
+        self.on_state_change = None
+
+    def _set_state(self, new_state: VADState) -> None:
+        """Update VAD state and fire callback."""
+        if self._state != new_state:
+            self._state = new_state
+            if self.on_state_change:
+                self.on_state_change(new_state)
+
+    def _start_trailing_timer(self) -> None:
+        """
+        Start the trailing timeout.
+        After postroll_ms, transition back to idle.
+        """
+        async def trailing_timeout():
+            await asyncio.sleep(self._config.postroll_ms / 1000.0)
+            self._set_state("idle")
+            self._trailing_task = None
+
+        loop = self._loop or asyncio.get_event_loop()
+        self._trailing_task = loop.create_task(trailing_timeout())
+
+    def _cancel_trailing_timer(self) -> None:
+        """Cancel the trailing timeout."""
+        if self._trailing_task is not None:
+            self._trailing_task.cancel()
+            self._trailing_task = None

dominus/start.py

@@ -342,6 +342,13 @@ class Dominus:
         # Secure namespace with proper audit context support
         self.db_secure = SecureNS(self)
 
+        # Oracle namespace (Speech-to-Text streaming)
+        from .namespaces.oracle import OracleNamespace
+        self.oracle = OracleNamespace(self)
+
+        # Alias for Node.js SDK parity (stt = oracle)
+        self.stt = self.oracle
+
         # Cache for JWT public key
         self._public_key_cache = None
 

{dominus_sdk_python_dev-2.4.0.dist-info → dominus_sdk_python_dev-2.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python-dev
-Version: 2.4.0
+Version: 2.5.0
 Summary: Python SDK for the Dominus Orchestrator Platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary
@@ -25,9 +25,20 @@ Requires-Dist: bcrypt>=4.0.0
 Requires-Dist: cryptography>=41.0.0
 Provides-Extra: jwt
 Requires-Dist: PyJWT>=2.8.0; extra == "jwt"
+Provides-Extra: oracle
+Requires-Dist: websockets>=12.0; extra == "oracle"
+Requires-Dist: sounddevice>=0.4.6; extra == "oracle"
+Requires-Dist: numpy>=1.24.0; extra == "oracle"
+Requires-Dist: webrtcvad>=2.0.10; extra == "oracle"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: PyJWT>=2.8.0; extra == "all"
+Requires-Dist: websockets>=12.0; extra == "all"
+Requires-Dist: sounddevice>=0.4.6; extra == "all"
+Requires-Dist: numpy>=1.24.0; extra == "all"
+Requires-Dist: webrtcvad>=2.0.10; extra == "all"
 
 # CB Dominus SDK for Python
 

{dominus_sdk_python_dev-2.4.0.dist-info → dominus_sdk_python_dev-2.5.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
-dominus/__init__.py,sha256=_gX9fwk5BlNvP1YEEmOGG7pftBiJYnY8PRZ9sHAoZL4,4841
+dominus/__init__.py,sha256=fBZgMu7J7o7DCUNH9PStQ873LW5n9IREXsuu6EsXO70,5132
 dominus/errors.py,sha256=Sfpg_4zlraE6fprdSu7RDNmSDv0Eg5OZRcPhNUQhNGs,5761
-dominus/start.py,sha256=H6QOEYw5_YK-lFZ7AhQpQPACvKPlb8R5sw_MA0rcsmQ,32503
+dominus/start.py,sha256=F_Z9qu8m5YLKk9uCeM9S2vnSfArDJVojoi6MDe8pNqE,32743
 dominus/config/__init__.py,sha256=nvLLNh4dM_MCqcfF3XFS2NnVn44q0RYHEfAPP-2G5To,434
 dominus/config/endpoints.py,sha256=fsV5c7vaicpJlF735o46FP4Xlu2Ap4rSvnNa4F0TOYg,1574
 dominus/helpers/__init__.py,sha256=cyoBvw1QJugtGt0gYitIz1yxOaMmBa-wMXqbh-fi4PU,61
@@ -9,8 +9,6 @@ dominus/helpers/cache.py,sha256=RgCTPLmHoOXGkxF-pLP9buKPkvZDYHtsLUxbTFjheJI,6028
 dominus/helpers/core.py,sha256=DeCo2sCmXJLnitJSDzRKcQGwYXyQOw1KRvzxDI6DQsA,24174
 dominus/helpers/crypto.py,sha256=XvP9ud5jJ9KPvIQmtAOeXZS4WUyCNb8X-RL_eOB7WNE,2890
 dominus/namespaces/__init__.py,sha256=Kh7tw-5LmY-CpZL2BdqbHc93QLjxTOCGLUVPwAqqDnE,659
-dominus/namespaces/_deprecated_crossover.py,sha256=NY73vatvc4CDgML9QMqmvoEjRr_t-Vq6FHtbby0M2-M,385
-dominus/namespaces/_deprecated_sql.py,sha256=U57p5hGFbsPEcNEl12m7tYTWux7j2rcCHbCjmNMJ8oY,38318
 dominus/namespaces/admin.py,sha256=qkGoteAJ6cqdNub4zL1mtyxAQtsM3-nUplRSgw2fMZY,1640
 dominus/namespaces/auth.py,sha256=Nqy4EOA1qMINvVuvf2-RnKPwN6TyLiD3vmz1G4J7TQg,55462
 dominus/namespaces/courier.py,sha256=WAhHpswhO8S_eEzn5zgBGhDqhgGxfDR_gs4i1rnotNw,6810
@@ -25,10 +23,14 @@ dominus/namespaces/portal.py,sha256=6T0ul2spnhcDORh1JN2v7zDbkdWqk0FblWKFIeUjSsA,
 dominus/namespaces/redis.py,sha256=WctuQdUddifDiato6QHntv1ulvAQVVC01iq_k2WUh9A,9384
 dominus/namespaces/secrets.py,sha256=6xhUJVeDBb5-AiwrwjozarwAc7SoiJ-2Rq6ByBAx684,3572
 dominus/namespaces/secure.py,sha256=9idGY5R6k7b-JM1SAF_1Gt-YV5OempyxFBflgLJieLo,7168
+dominus/namespaces/oracle/__init__.py,sha256=XiJ8P-vFln73p4r1_ZXgmNQvawkNUt5htuGD51JCoBA,4584
+dominus/namespaces/oracle/audio_capture.py,sha256=1-QcoAHYT1idEBGAJ7g4qpu5QeKdmwiyWciB6K0WkNM,11201
+dominus/namespaces/oracle/oracle_websocket.py,sha256=VsKKPTZmtdchoXj9bFel3hrWUVELS-5UD7LNFWlDdfg,7540
+dominus/namespaces/oracle/session.py,sha256=1As6q-bs0Ynoz3fsNk18E7CuouPROnVadCY_HeHRTkw,7998
+dominus/namespaces/oracle/types.py,sha256=YGwb-PfKikRGNk4af5Av2DD9YPLJpogM21Co9X4T_cU,3517
+dominus/namespaces/oracle/vad_gate.py,sha256=Gpb5q72-MSGYm4PVK64E4w6kawx5AMb1SsJ2uOJrtFw,9010
 dominus/services/__init__.py,sha256=LQl5sx6DHhX1xCN3MRoUgffxqwm3Mfm525hijyFods8,43
-dominus/services/_deprecated_architect.py,sha256=EAMhUK8C_4DLgYyKGVqcXrroEoAenWeuKWnPMowGMQk,14985
-dominus/services/_deprecated_sovereign.py,sha256=is9SQVCcmcGUEFKULqitHlk67pfpfkQE-ApU-gVjIEE,3511
-dominus_sdk_python_dev-2.4.0.dist-info/METADATA,sha256=yKb6wAvg7axw31k6XZ20krPsnoJCknhMo1JQMcoFvbg,16918
-dominus_sdk_python_dev-2.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dominus_sdk_python_dev-2.4.0.dist-info/top_level.txt,sha256=515zxMIbX0DpheRbjvNqKIt_AFqdFjX41jtyp_SqLf4,8
-dominus_sdk_python_dev-2.4.0.dist-info/RECORD,,
+dominus_sdk_python_dev-2.5.0.dist-info/METADATA,sha256=j4BWCGfmmcMqgtDbt9VHq-oBzmARLshuRIdCr27G-aM,17401
+dominus_sdk_python_dev-2.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dominus_sdk_python_dev-2.5.0.dist-info/top_level.txt,sha256=515zxMIbX0DpheRbjvNqKIt_AFqdFjX41jtyp_SqLf4,8
+dominus_sdk_python_dev-2.5.0.dist-info/RECORD,,

dominus/namespaces/_deprecated_crossover.py

@@ -1,10 +0,0 @@
-"""Crossover (admin) operations namespace - DEPRECATED
-
-Note: This namespace has been removed from the SDK.
-Provisioning and admin operations should be done via Architect's
-/api/crossover endpoint directly, not through the SDK.
-
-This file is kept as a placeholder to prevent import errors in
-any code that may still reference it.
-"""
-# Empty file - all crossover functionality removed