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

dominus/namespaces/oracle/oracle_websocket.py

@@ -0,0 +1,230 @@
+"""
+OracleWebSocket - WebSocket wrapper for Oracle streaming (INTERNAL)
+
+Handles:
+- First-message authentication (browser WS doesn't support headers)
+- Binary frames for audio (NOT base64)
+- JSON frames for control messages
+- Ping/pong keepalive during IDLE
+- Transcript parsing and callback firing
+
+This module is INTERNAL and should NOT be exported publicly.
+"""
+
+import asyncio
+import json
+from typing import Callable, Optional
+from dataclasses import dataclass
+
+try:
+    import websockets
+    from websockets.client import WebSocketClientProtocol
+    WEBSOCKETS_AVAILABLE = True
+except ImportError:
+    WEBSOCKETS_AVAILABLE = False
+    WebSocketClientProtocol = None
+
+
+@dataclass
+class OracleWebSocketConfig:
+    """Configuration for OracleWebSocket."""
+    ping_interval_ms: int = 10000
+
+
+class OracleWebSocket:
+    """
+    OracleWebSocket - Manages WebSocket connection to Oracle service.
+    """
+
+    def __init__(self, base_url: str, config: Optional[OracleWebSocketConfig] = None):
+        if not WEBSOCKETS_AVAILABLE:
+            raise ImportError(
+                "websockets package is required for Oracle streaming. "
+                "Install with: pip install websockets"
+            )
+
+        self._base_url = base_url
+        self._config = config or OracleWebSocketConfig()
+        self._ws: Optional[WebSocketClientProtocol] = None
+        self._authenticated = False
+        self._ping_task: Optional[asyncio.Task] = None
+        self._receive_task: Optional[asyncio.Task] = None
+
+        # Callbacks
+        self.on_transcript: Optional[Callable[[str, bool, bool], None]] = None
+        self.on_error: Optional[Callable[[Exception], None]] = None
+        self.on_close: Optional[Callable[[], None]] = None
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if WebSocket is connected and authenticated."""
+        return (
+            self._ws is not None
+            and self._ws.open
+            and self._authenticated
+        )
+
+    async def connect(self, user_token: str) -> None:
+        """
+        Connect to Oracle WebSocket endpoint with first-message auth.
+
+        Args:
+            user_token: User JWT for authentication
+
+        Raises:
+            Exception: If connection or authentication fails
+        """
+        # Convert HTTP URL to WebSocket URL
+        ws_url = self._build_websocket_url()
+
+        try:
+            self._ws = await websockets.connect(ws_url)
+        except Exception as e:
+            raise Exception(f"Failed to create WebSocket: {e}")
+
+        # Send first-message auth
+        auth_message = json.dumps({
+            "type": "auth",
+            "token": user_token,
+        })
+        await self._ws.send(auth_message)
+
+        # Wait for ready message
+        try:
+            response = await asyncio.wait_for(self._ws.recv(), timeout=10.0)
+            data = json.loads(response)
+
+            if data.get("type") == "ready":
+                self._authenticated = True
+                self._start_ping_interval()
+                self._start_receive_loop()
+            elif data.get("type") == "error":
+                raise Exception(f"Authentication failed: {data.get('message')}")
+            else:
+                raise Exception(f"Unexpected response type: {data.get('type')}")
+
+        except asyncio.TimeoutError:
+            await self._ws.close()
+            raise Exception("Authentication timeout")
+
+    def send_binary(self, pcm_frame: bytes) -> None:
+        """
+        Send binary PCM audio frame.
+        Only called by VADGate - NOT exposed publicly.
+
+        Args:
+            pcm_frame: Raw PCM audio data
+        """
+        if self._ws and self._ws.open and self._authenticated:
+            asyncio.create_task(self._ws.send(pcm_frame))
+
+    async def send_ping(self) -> None:
+        """Send a ping message for keepalive."""
+        if self._ws and self._ws.open and self._authenticated:
+            await self._ws.send(json.dumps({"type": "ping"}))
+
+    async def close(self) -> None:
+        """Close the WebSocket connection gracefully."""
+        self._stop_ping_interval()
+        self._stop_receive_loop()
+
+        if self._ws:
+            # Send close message before closing
+            if self._ws.open:
+                try:
+                    await self._ws.send(json.dumps({"type": "close"}))
+                except Exception:
+                    pass  # Ignore send errors during close
+
+            await self._ws.close()
+            self._ws = None
+
+        self._authenticated = False
+
+    def _build_websocket_url(self) -> str:
+        """Build WebSocket URL from base URL."""
+        # Replace http(s) with ws(s)
+        if self._base_url.startswith("https"):
+            ws_protocol = "wss"
+            http_protocol = "https"
+        else:
+            ws_protocol = "ws"
+            http_protocol = "http"
+
+        return self._base_url.replace(http_protocol, ws_protocol) + "/api/oracle/stream"
+
+    def _start_receive_loop(self) -> None:
+        """Start the receive loop for incoming messages."""
+        async def receive_loop():
+            try:
+                while self._ws and self._ws.open:
+                    try:
+                        message = await self._ws.recv()
+                        await self._handle_message(message)
+                    except websockets.exceptions.ConnectionClosed:
+                        break
+            finally:
+                self._authenticated = False
+                if self.on_close:
+                    self.on_close()
+
+        self._receive_task = asyncio.create_task(receive_loop())
+
+    def _stop_receive_loop(self) -> None:
+        """Stop the receive loop."""
+        if self._receive_task:
+            self._receive_task.cancel()
+            self._receive_task = None
+
+    async def _handle_message(self, message) -> None:
+        """Handle incoming WebSocket message."""
+        # Binary messages are not expected from server (audio is one-way)
+        if isinstance(message, bytes):
+            return
+
+        # Parse JSON message
+        try:
+            data = json.loads(message)
+        except json.JSONDecodeError:
+            print("[OracleSDK] Received invalid JSON from server")
+            return
+
+        msg_type = data.get("type")
+
+        if msg_type == "transcript":
+            text = data.get("text", "")
+            is_final = data.get("is_final", False)
+            speech_final = data.get("speech_final", False)
+
+            print(f"[OracleSDK] Transcript received: text={text[:40] if text else ''!r}, "
+                  f"is_final={is_final}, speech_final={speech_final}")
+
+            if self.on_transcript:
+                self.on_transcript(text, is_final, speech_final)
+
+        elif msg_type == "pong":
+            # Keepalive response - no action needed
+            pass
+
+        elif msg_type == "error":
+            error = Exception(data.get("message", "Unknown error"))
+            if self.on_error:
+                self.on_error(error)
+
+        else:
+            print(f"[OracleSDK] Unknown message type: {msg_type}")
+
+    def _start_ping_interval(self) -> None:
+        """Start ping interval for keepalive."""
+        async def ping_loop():
+            while True:
+                await asyncio.sleep(self._config.ping_interval_ms / 1000.0)
+                await self.send_ping()
+
+        self._ping_task = asyncio.create_task(ping_loop())
+
+    def _stop_ping_interval(self) -> None:
+        """Stop ping interval."""
+        if self._ping_task:
+            self._ping_task.cancel()
+            self._ping_task = None

dominus/namespaces/oracle/session.py

@@ -0,0 +1,252 @@
+"""
+OracleSession - Main session class for streaming transcription.
+
+Provides the public API for Oracle streaming:
+- start() / stop() lifecycle
+- Event callbacks for transcripts, VAD state, errors
+- NO send_audio() exposed - VAD gates all audio automatically
+
+The session handles everything internally:
+- Microphone access and audio capture
+- Resampling to 16kHz mono PCM
+- VAD gating (only sends speech, not silence)
+- WebSocket connection to Oracle
+- Ping/pong keepalive during IDLE
+"""
+
+import asyncio
+from typing import Callable, Optional, List
+
+from .oracle_websocket import OracleWebSocket, OracleWebSocketConfig
+from .vad_gate import VADGate
+from .audio_capture import AudioCapture
+from .types import VADState, ResolvedOracleSessionOptions
+
+
+class OracleSession:
+    """
+    OracleSession - Real-time speech-to-text with VAD gating.
+
+    Usage:
+        session = dominus.oracle.create_session(user_jwt)
+
+        session.on_ready = lambda: print('Ready')
+        session.on_interim = lambda text: set_live_text(text)
+        session.on_utterance = lambda text: send_to_curator(text)
+        session.on_vad_state_change = lambda state: update_mic_icon(state)
+
+        await session.start()
+        # ... user speaks ...
+        await session.stop()
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        user_token: str,
+        options: ResolvedOracleSessionOptions
+    ):
+        self._user_token = user_token
+        self._is_active = False
+        self._vad_state: VADState = "idle"
+
+        # Track accumulated transcript for utterance detection
+        # Since VAD stops sending audio before Deepgram's utterance_end_ms,
+        # we use VAD TRAILING->IDLE transition as utterance boundary
+        self._pending_utterance = ""
+
+        # Initialize internal components
+        self._ws = OracleWebSocket(
+            base_url,
+            OracleWebSocketConfig(ping_interval_ms=options.ping_interval_ms)
+        )
+        self._vad = VADGate(options)
+        self._audio = AudioCapture()
+
+        # ========== EVENT CALLBACKS ==========
+
+        # Called when session is ready to receive speech
+        self.on_ready: Optional[Callable[[], None]] = None
+
+        # Called with interim transcripts (may change)
+        self.on_interim: Optional[Callable[[str], None]] = None
+
+        # Called when a transcript segment is finalized
+        self.on_final: Optional[Callable[[str], None]] = None
+
+        # Called when user finishes an utterance (trigger for Curator)
+        self.on_utterance: Optional[Callable[[str], None]] = None
+
+        # Called on any error
+        self.on_error: Optional[Callable[[Exception], None]] = None
+
+        # Called when session closes
+        self.on_close: Optional[Callable[[], None]] = None
+
+        # Called when VAD state changes (for UI indicators)
+        self.on_vad_state_change: Optional[Callable[[VADState], None]] = None
+
+    # ========== PUBLIC GETTERS ==========
+
+    @property
+    def is_active(self) -> bool:
+        """Check if session is currently active."""
+        return self._is_active
+
+    @property
+    def vad_state(self) -> VADState:
+        """Get current VAD state."""
+        return self._vad_state
+
+    # ========== LIFECYCLE METHODS ==========
+
+    async def start(self) -> None:
+        """
+        Start the transcription session.
+
+        - Requests microphone permission
+        - Connects WebSocket to Oracle
+        - Begins VAD-gated audio streaming
+
+        Raises:
+            Exception: If mic permission denied or connection fails
+        """
+        if self._is_active:
+            return
+
+        try:
+            # 1. Initialize VAD
+            await self._vad.initialize()
+
+            # 2. Connect WebSocket with first-message auth
+            await self._ws.connect(self._user_token)
+
+            # 3. Wire up transcript events
+            def on_transcript(text: str, is_final: bool, speech_final: bool):
+                if not is_final:
+                    # Interim: show in live view (may change)
+                    if self.on_interim:
+                        self.on_interim(text)
+                else:
+                    # Final: accumulate for utterance
+                    if self.on_final:
+                        self.on_final(text)
+                    # Accumulate finals - space-separated
+                    if self._pending_utterance:
+                        self._pending_utterance += " " + text
+                    else:
+                        self._pending_utterance = text
+
+                # If Deepgram does send speech_final, honor it
+                if speech_final and text:
+                    self._pending_utterance = ""  # Clear since we're emitting
+                    if self.on_utterance:
+                        self.on_utterance(text)
+
+            self._ws.on_transcript = on_transcript
+
+            self._ws.on_error = lambda error: (
+                self.on_error(error) if self.on_error else None
+            )
+
+            def on_ws_close():
+                self._is_active = False
+                if self.on_close:
+                    self.on_close()
+
+            self._ws.on_close = on_ws_close
+
+            # 4. Start audio capture
+            await self._audio.start()
+
+            # 5. Wire audio through VAD gate
+            def on_audio_frame(pcm_frame: bytes):
+                self._vad.process_frame(pcm_frame)
+
+            self._audio.on_frame = on_audio_frame
+
+            # 6. VAD gate controls what gets sent
+            def on_send_audio(frames: List[bytes]):
+                for frame in frames:
+                    self._ws.send_binary(frame)
+
+            self._vad.on_send_audio = on_send_audio
+
+            def on_vad_state_change(state: VADState):
+                prev_state = self._vad_state
+                self._vad_state = state
+
+                if self.on_vad_state_change:
+                    self.on_vad_state_change(state)
+
+                # When VAD transitions to IDLE from TRAILING, emit accumulated utterance
+                if state == "idle" and (prev_state == "trailing" or prev_state == "speaking"):
+                    if self._pending_utterance.strip():
+                        print(f"[OracleSDK] VAD->IDLE: emitting utterance: "
+                              f"{self._pending_utterance[:50]!r}")
+                        if self.on_utterance:
+                            self.on_utterance(self._pending_utterance.strip())
+                        self._pending_utterance = ""
+
+            self._vad.on_state_change = on_vad_state_change
+
+            self._is_active = True
+
+            if self.on_ready:
+                self.on_ready()
+
+        except Exception as e:
+            # Clean up on failure
+            await self._cleanup()
+            raise e
+
+    async def stop(self) -> None:
+        """
+        Stop the transcription session.
+
+        - Stops microphone capture
+        - Closes WebSocket connection
+        - Cleans up resources
+        """
+        if not self._is_active:
+            return
+
+        self._is_active = False
+        await self._cleanup()
+
+        if self.on_close:
+            self.on_close()
+
+    # ========== PRIVATE METHODS ==========
+
+    async def _cleanup(self) -> None:
+        """Clean up all resources."""
+        # Stop audio capture
+        await self._audio.stop()
+
+        # Close WebSocket
+        await self._ws.close()
+
+        # Reset VAD state
+        self._vad.reset()
+        self._vad_state = "idle"
+
+        # Clear pending utterance
+        self._pending_utterance = ""
+
+    def dispose(self) -> None:
+        """Dispose of all resources (for cleanup on unmount)."""
+        asyncio.create_task(self.stop())
+
+        # Clear all callbacks
+        self.on_ready = None
+        self.on_interim = None
+        self.on_final = None
+        self.on_utterance = None
+        self.on_error = None
+        self.on_close = None
+        self.on_vad_state_change = None
+
+        # Dispose internal components
+        self._audio.dispose()
+        self._vad.dispose()

dominus/namespaces/oracle/types.py

@@ -0,0 +1,127 @@
+"""
+Oracle Namespace Types - Public interfaces for streaming transcription.
+
+Oracle provides real-time speech-to-text via Deepgram streaming,
+with built-in VAD (Voice Activity Detection) for cost optimization.
+"""
+
+from typing import Literal, Optional, Callable, TypedDict
+from dataclasses import dataclass, field
+
+
+# VAD (Voice Activity Detection) states
+VADState = Literal["idle", "armed", "speaking", "trailing"]
+
+
+@dataclass
+class OracleSessionOptions:
+    """Configuration options for OracleSession."""
+
+    # Pre-roll buffer duration in ms (default: 320)
+    preroll_ms: int = 320
+
+    # Post-roll duration in ms (default: 800)
+    postroll_ms: int = 800
+
+    # VAD confirmation time in ms (default: 160)
+    armed_confirm_ms: int = 160
+
+    # VAD speech threshold 0-1 (default: 0.5) - used for energy-based fallback
+    vad_threshold: float = 0.5
+
+    # Energy threshold for fallback VAD (default: 800)
+    energy_threshold: int = 800
+
+    # Ping interval in ms for keepalive (default: 10000)
+    ping_interval_ms: int = 10000
+
+
+@dataclass
+class ResolvedOracleSessionOptions:
+    """Resolved session options with all defaults applied."""
+
+    preroll_ms: int
+    postroll_ms: int
+    armed_confirm_ms: int
+    vad_threshold: float
+    energy_threshold: int
+    ping_interval_ms: int
+
+
+# Default configuration values
+DEFAULT_OPTIONS = ResolvedOracleSessionOptions(
+    preroll_ms=320,           # 16 frames x 20ms
+    postroll_ms=800,          # Post-roll trailing duration
+    armed_confirm_ms=160,     # 8 frames x 20ms to confirm speech
+    vad_threshold=0.5,        # VAD threshold
+    energy_threshold=800,     # Energy-based fallback threshold
+    ping_interval_ms=10000,   # 10 second ping interval
+)
+
+
+@dataclass
+class AudioConfig:
+    """Audio configuration constants."""
+
+    SAMPLE_RATE: int = 16000       # 16kHz
+    CHANNELS: int = 1               # Mono
+    FRAME_DURATION_MS: int = 20     # 20ms frames
+    FRAME_SIZE_BYTES: int = 640     # 320 samples x 2 bytes per sample
+    SAMPLES_PER_FRAME: int = 320    # 16kHz x 20ms
+
+
+AUDIO_CONFIG = AudioConfig()
+
+
+class ServerReadyMessage(TypedDict):
+    """Server ready message."""
+    type: Literal["ready"]
+
+
+class ServerTranscriptMessage(TypedDict):
+    """Server transcript message."""
+    type: Literal["transcript"]
+    text: str
+    is_final: bool
+    speech_final: bool
+
+
+class ServerPongMessage(TypedDict):
+    """Server pong message."""
+    type: Literal["pong"]
+
+
+class ServerErrorMessage(TypedDict):
+    """Server error message."""
+    type: Literal["error"]
+    message: str
+
+
+# Union type for server messages
+ServerMessage = ServerReadyMessage | ServerTranscriptMessage | ServerPongMessage | ServerErrorMessage
+
+
+@dataclass
+class OracleSessionCallbacks:
+    """Event callbacks for OracleSession."""
+
+    # Called when session is ready to receive speech
+    on_ready: Optional[Callable[[], None]] = None
+
+    # Called with interim transcripts (may change)
+    on_interim: Optional[Callable[[str], None]] = None
+
+    # Called when a transcript segment is finalized
+    on_final: Optional[Callable[[str], None]] = None
+
+    # Called when user finishes an utterance (trigger for Curator)
+    on_utterance: Optional[Callable[[str], None]] = None
+
+    # Called on any error
+    on_error: Optional[Callable[[Exception], None]] = None
+
+    # Called when session closes
+    on_close: Optional[Callable[[], None]] = None
+
+    # Called when VAD state changes (for UI indicators)
+    on_vad_state_change: Optional[Callable[[VADState], None]] = None