dominus-sdk-python-dev 2.3.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

@@ -251,31 +251,6 @@ class SecureNamespace:
         )
 
 
-class OpenNamespace:
-    """Open user namespace - Returns DSN string for dominus_open database."""
-
-    def __init__(self, _execute_command):
-        self._execute = _execute_command
-
-    async def dsn(self) -> str:
-        """
-        Get the full DSN connection string for open_user role.
-
-        Returns the complete PostgreSQL connection URI for the dominus_open
-        database that can be used directly by clients to connect.
-        """
-        return await self._execute("sql.open.get_dsn")
-
-
-class HealthNamespace:
-    """Health check operations namespace."""
-
-    def __init__(self, _execute_command):
-        self._execute = _execute_command
-
-    async def check(self) -> Dict[str, Any]:
-        """Check health of all services."""
-        return await self._execute("health.check")
 
 
 class Dominus:
@@ -324,10 +299,8 @@ class Dominus:
 
         self._execute = _execute_command
 
-        # Initialize minimal namespaces
+        # Initialize legacy flat API namespaces (backward compatibility)
         self.secure = SecureNamespace(_execute_command)
-        self.open = OpenNamespace(_execute_command)
-        self.health = HealthNamespace(_execute_command)
 
         # Initialize portal namespace (needs client reference for _request)
         from .namespaces.portal import PortalNamespace
@@ -337,24 +310,45 @@ class Dominus:
         from .namespaces.fastapi import FastAPINamespace
         self.fastapi = FastAPINamespace(self)
 
-        # Initialize full namespaces (matching Node.js SDK pattern)
+        # Initialize all namespaces (matching Node.js SDK pattern)
         from .namespaces.db import DbNamespace
         from .namespaces.auth import AuthNamespace
         from .namespaces.ddl import DdlNamespace
         from .namespaces.files import FilesNamespace
         from .namespaces.admin import AdminNamespace
         from .namespaces.secure import SecureNamespace as SecureNS
-
+        from .namespaces.secrets import SecretsNamespace
+        from .namespaces.redis import RedisNamespace
+        from .namespaces.logs import LogsNamespace
+        from .namespaces.courier import CourierNamespace
+        from .namespaces.health import HealthNamespace
+        from .namespaces.open import OpenNamespace
+
+        # Core namespaces
         self.db = DbNamespace(self)
         self.auth = AuthNamespace(self)
         self.ddl = DdlNamespace(self)
         self.files = FilesNamespace(self)
         self.admin = AdminNamespace(self)
 
-        # Note: self.secure is already defined above as the flat API namespace
-        # The proper SecureNS namespace is available as dominus.db_secure for direct access
+        # Additional namespaces (Node.js SDK parity)
+        self.secrets = SecretsNamespace(self)
+        self.redis = RedisNamespace(self)
+        self.logs = LogsNamespace(self)
+        self.courier = CourierNamespace(self)
+        self.health = HealthNamespace(self)
+        self.open = OpenNamespace(self)
+
+        # 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.3.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.3.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
 
@@ -417,8 +428,8 @@ from dominus import (
     ConflictError,
     ServiceError,
     SecureTableError,
-    ConnectionError,
-    TimeoutError,
+    DominusConnectionError,  # Renamed to avoid shadowing built-in
+    DominusTimeoutError,     # Renamed to avoid shadowing built-in
 )
 
 try:
@@ -445,6 +456,7 @@ except DominusError as e:
 
 | Error | Status | Description |
 |-------|--------|-------------|
+| `DominusError` | - | Base class for all SDK errors |
 | `AuthenticationError` | 401 | Invalid or missing token |
 | `AuthorizationError` | 403 | Insufficient permissions |
 | `NotFoundError` | 404 | Resource not found |
@@ -452,8 +464,8 @@ except DominusError as e:
 | `ConflictError` | 409 | Duplicate or version conflict |
 | `ServiceError` | 5xx | Backend service error |
 | `SecureTableError` | 403 | Missing reason for secure table |
-| `ConnectionError` | - | Network connection failed |
-| `TimeoutError` | 504 | Request timed out |
+| `DominusConnectionError` | - | Network connection failed |
+| `DominusTimeoutError` | 504 | Request timed out |
 
 ## Configuration
 
@@ -551,10 +563,13 @@ async def get_all_users(page_size: int = 100):
 
 ## Version
 
-**v2.1.6** - Latest release with navigation routes and page scope methods
+**v2.4.0** - Full namespace parity with Node.js SDK
 
 ### Changelog
 
+- **v2.4.0** - Full parity with Node.js SDK: all namespaces properly initialized, error classes exported, cache utilities exposed
+- **v2.3.0** - Add comprehensive auth namespace with 100+ methods
+- **v2.2.0** - Add DDL schema builder and migration methods
 - **v2.1.6** - Fix navigation routes and add page scope methods
 - **v2.1.5** - Add PSK-only client login
 - **v2.1.4** - Make `tenant_id` optional in login methods

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

@@ -1,16 +1,14 @@
-dominus/__init__.py,sha256=-VkTYvkoJS7ltZr6A3qOfqqU1ueKkYv3dhznfGnJ3oY,2990
+dominus/__init__.py,sha256=fBZgMu7J7o7DCUNH9PStQ873LW5n9IREXsuu6EsXO70,5132
 dominus/errors.py,sha256=Sfpg_4zlraE6fprdSu7RDNmSDv0Eg5OZRcPhNUQhNGs,5761
-dominus/start.py,sha256=mzBglBZ38jPPuHtLGJ7IIB5r_bnMR4_a5i4fZbyudQ8,32823
+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
 dominus/helpers/auth.py,sha256=IVZLelikaGIAZvyc-q7EoPd8fBNVlGffGXQkTP4x5Fk,633
-dominus/helpers/cache.py,sha256=U09xylQipotRUNdB3zsQRcjmeYgKzu639P-ucNgks5M,5721
+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.3.0.dist-info/METADATA,sha256=zb7sLkwxGc2bPKH7WE3j_yYPJAxmQqRXcAQw9js_svU,16520
-dominus_sdk_python_dev-2.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dominus_sdk_python_dev-2.3.0.dist-info/top_level.txt,sha256=515zxMIbX0DpheRbjvNqKIt_AFqdFjX41jtyp_SqLf4,8
-dominus_sdk_python_dev-2.3.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