orbitalsai 1.0.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

orbitalsai/streaming/events.py

@@ -0,0 +1,360 @@
+"""
+OrbitalsAI Streaming Event Handlers
+
+Event handler classes for streaming transcription callbacks.
+"""
+
+from typing import Any, Dict, Optional
+from abc import ABC
+import logging
+import sys
+
+logger = logging.getLogger("orbitalsai.streaming")
+
+
+class StreamingEventHandlers(ABC):
+    """
+    Base class for streaming event handlers.
+    
+    Override methods as needed to handle streaming events. All methods have
+    default no-op implementations, so you only need to override the events
+    you care about.
+    
+    Example:
+        class MyHandlers(StreamingEventHandlers):
+            def on_transcript_final(self, transcript: str, metadata: dict) -> None:
+                print(f"Final: {transcript}")
+                print(f"Cost: ${metadata['cost']:.4f}")
+        
+        async with AsyncStreamingClient(api_key="...") as client:
+            await client.connect(MyHandlers())
+    """
+    
+    def on_open(self, session_info: Dict[str, Any]) -> None:
+        """
+        Called when WebSocket connection is established.
+        
+        Args:
+            session_info: Dictionary containing:
+                - session_id: Unique session identifier
+                - language: Current transcription language
+                - supported_languages: List of supported languages
+        """
+        pass
+    
+    def on_transcript_partial(self, transcript: str) -> None:
+        """
+        Called for interim transcription results.
+        
+        Partial transcripts may change as more audio is processed.
+        Use these for real-time display but don't rely on them for final output.
+        
+        Args:
+            transcript: Partial transcript text (may change)
+        """
+        pass
+    
+    def on_transcript_final(self, transcript: str, metadata: Dict[str, Any]) -> None:
+        """
+        Called for final transcription results.
+        
+        Final transcripts are stable and won't change. This is the definitive
+        transcription for the processed audio segment.
+        
+        Args:
+            transcript: Final transcript text
+            metadata: Dictionary containing:
+                - cost: Cost of this segment in dollars
+                - audio_seconds: Duration of processed audio
+                - remaining_percent: Percentage of credits remaining
+                - capped: Whether billing was capped due to low balance
+        """
+        pass
+    
+    def on_speech_start(self) -> None:
+        """
+        Called when speech is detected.
+        
+        Indicates that the VAD (Voice Activity Detection) has detected
+        the start of speech in the audio stream.
+        """
+        pass
+    
+    def on_speech_end(self) -> None:
+        """
+        Called when speech ends (silence detected).
+        
+        Indicates that the VAD has detected a pause or end of speech.
+        This typically triggers processing of the accumulated audio.
+        """
+        pass
+    
+    def on_language_detected(self, language: str) -> None:
+        """
+        Called when language is auto-detected or changed.
+        
+        Args:
+            language: The detected or set language
+        """
+        pass
+    
+    def on_sample_rate_changed(self, sample_rate: int) -> None:
+        """
+        Called when sample rate is changed.
+        
+        Args:
+            sample_rate: The new sample rate in Hz
+        """
+        pass
+    
+    def on_flushed(self) -> None:
+        """
+        Called when a flush operation completes.
+        
+        Indicates that all buffered audio has been processed and
+        final transcripts have been emitted.
+        """
+        pass
+    
+    def on_credits_warning(self, remaining_percent: int) -> None:
+        """
+        Called when credits fall below 20%.
+        
+        This is an early warning to top up credits before they run out.
+        
+        Args:
+            remaining_percent: Percentage of credits remaining (0-20)
+        """
+        pass
+    
+    def on_credits_critical(self, remaining_percent: int) -> None:
+        """
+        Called when credits fall below 5%.
+        
+        Critical warning - credits are about to run out.
+        
+        Args:
+            remaining_percent: Percentage of credits remaining (0-5)
+        """
+        pass
+    
+    def on_credits_exhausted(self) -> None:
+        """
+        Called when credits are exhausted.
+        
+        The connection will be closed after this event. User needs to
+        top up credits before continuing.
+        """
+        pass
+    
+    def on_error(self, error: Exception) -> None:
+        """
+        Called when an error occurs.
+        
+        Args:
+            error: The exception that occurred
+        """
+        pass
+    
+    def on_close(self, code: int, reason: str) -> None:
+        """
+        Called when WebSocket connection closes.
+        
+        Args:
+            code: WebSocket close code
+            reason: Human-readable close reason
+        """
+        pass
+
+
+class PrintingEventHandlers(StreamingEventHandlers):
+    """
+    Event handlers that print all events to stdout.
+    
+    Useful for debugging and testing. Shows timestamps and formatted
+    output for all streaming events.
+    
+    Example:
+        async with AsyncStreamingClient(api_key="...") as client:
+            await client.connect(PrintingEventHandlers())
+    """
+    
+    def __init__(self, file=None, show_partials: bool = True):
+        """
+        Initialize printing event handlers.
+        
+        Args:
+            file: File to print to (default: sys.stdout)
+            show_partials: Whether to print partial transcripts (default: True)
+        """
+        self.file = file or sys.stdout
+        self.show_partials = show_partials
+    
+    def _print(self, message: str) -> None:
+        """Print a message with timestamp."""
+        from datetime import datetime
+        timestamp = datetime.now().strftime("%H:%M:%S.%f")[:-3]
+        print(f"[{timestamp}] {message}", file=self.file, flush=True)
+    
+    def on_open(self, session_info: Dict[str, Any]) -> None:
+        self._print(f"🔗 Connected: session={session_info.get('session_id', 'unknown')}")
+        self._print(f"   Language: {session_info.get('language', 'unknown')}")
+        languages = session_info.get('supported_languages', [])
+        self._print(f"   Supported: {', '.join(languages)}")
+    
+    def on_transcript_partial(self, transcript: str) -> None:
+        if self.show_partials:
+            self._print(f"📝 Partial: {transcript}")
+    
+    def on_transcript_final(self, transcript: str, metadata: Dict[str, Any]) -> None:
+        self._print(f"✅ Final: {transcript}")
+        cost = metadata.get('cost', 0)
+        seconds = metadata.get('audio_seconds', 0)
+        remaining = metadata.get('remaining_percent', 100)
+        self._print(f"   Cost: ${cost:.4f} | Duration: {seconds:.1f}s | Credits: {remaining}%")
+    
+    def on_speech_start(self) -> None:
+        self._print("🎤 Speech started")
+    
+    def on_speech_end(self) -> None:
+        self._print("🔇 Speech ended")
+    
+    def on_language_detected(self, language: str) -> None:
+        self._print(f"🌐 Language set: {language}")
+    
+    def on_sample_rate_changed(self, sample_rate: int) -> None:
+        self._print(f"📊 Sample rate set: {sample_rate} Hz")
+    
+    def on_flushed(self) -> None:
+        self._print("💨 Flushed")
+    
+    def on_credits_warning(self, remaining_percent: int) -> None:
+        self._print(f"⚠️  Credits warning: {remaining_percent}% remaining")
+    
+    def on_credits_critical(self, remaining_percent: int) -> None:
+        self._print(f"🚨 Credits critical: {remaining_percent}% remaining")
+    
+    def on_credits_exhausted(self) -> None:
+        self._print("❌ Credits exhausted! Please top up.")
+    
+    def on_error(self, error: Exception) -> None:
+        self._print(f"❌ Error: {error}")
+    
+    def on_close(self, code: int, reason: str) -> None:
+        self._print(f"🔌 Disconnected: code={code}, reason={reason}")
+
+
+class CallbackEventHandlers(StreamingEventHandlers):
+    """
+    Event handlers using callback functions.
+    
+    Allows passing callback functions directly instead of subclassing.
+    Useful for simple use cases where you only need a few handlers.
+    
+    Example:
+        handlers = CallbackEventHandlers(
+            on_final=lambda text, meta: print(f"Got: {text}"),
+            on_error=lambda e: print(f"Error: {e}")
+        )
+        await client.connect(handlers)
+    """
+    
+    def __init__(
+        self,
+        on_open: Optional[callable] = None,
+        on_partial: Optional[callable] = None,
+        on_final: Optional[callable] = None,
+        on_speech_start: Optional[callable] = None,
+        on_speech_end: Optional[callable] = None,
+        on_language_detected: Optional[callable] = None,
+        on_sample_rate_changed: Optional[callable] = None,
+        on_flushed: Optional[callable] = None,
+        on_credits_warning: Optional[callable] = None,
+        on_credits_critical: Optional[callable] = None,
+        on_credits_exhausted: Optional[callable] = None,
+        on_error: Optional[callable] = None,
+        on_close: Optional[callable] = None,
+    ):
+        """
+        Initialize callback event handlers.
+        
+        Args:
+            on_open: Callback for connection open (session_info: dict)
+            on_partial: Callback for partial transcripts (text: str)
+            on_final: Callback for final transcripts (text: str, metadata: dict)
+            on_speech_start: Callback for speech start ()
+            on_speech_end: Callback for speech end ()
+            on_language_detected: Callback for language detection (language: str)
+            on_sample_rate_changed: Callback for sample rate change (sample_rate: int)
+            on_flushed: Callback for flush completion ()
+            on_credits_warning: Callback for credits warning (remaining_percent: int)
+            on_credits_critical: Callback for credits critical (remaining_percent: int)
+            on_credits_exhausted: Callback for credits exhausted ()
+            on_error: Callback for errors (error: Exception)
+            on_close: Callback for connection close (code: int, reason: str)
+        """
+        self._on_open = on_open
+        self._on_partial = on_partial
+        self._on_final = on_final
+        self._on_speech_start = on_speech_start
+        self._on_speech_end = on_speech_end
+        self._on_language_detected = on_language_detected
+        self._on_sample_rate_changed = on_sample_rate_changed
+        self._on_flushed = on_flushed
+        self._on_credits_warning = on_credits_warning
+        self._on_credits_critical = on_credits_critical
+        self._on_credits_exhausted = on_credits_exhausted
+        self._on_error = on_error
+        self._on_close = on_close
+    
+    def on_open(self, session_info: Dict[str, Any]) -> None:
+        if self._on_open:
+            self._on_open(session_info)
+    
+    def on_transcript_partial(self, transcript: str) -> None:
+        if self._on_partial:
+            self._on_partial(transcript)
+    
+    def on_transcript_final(self, transcript: str, metadata: Dict[str, Any]) -> None:
+        if self._on_final:
+            self._on_final(transcript, metadata)
+    
+    def on_speech_start(self) -> None:
+        if self._on_speech_start:
+            self._on_speech_start()
+    
+    def on_speech_end(self) -> None:
+        if self._on_speech_end:
+            self._on_speech_end()
+    
+    def on_language_detected(self, language: str) -> None:
+        if self._on_language_detected:
+            self._on_language_detected(language)
+    
+    def on_sample_rate_changed(self, sample_rate: int) -> None:
+        if self._on_sample_rate_changed:
+            self._on_sample_rate_changed(sample_rate)
+    
+    def on_flushed(self) -> None:
+        if self._on_flushed:
+            self._on_flushed()
+    
+    def on_credits_warning(self, remaining_percent: int) -> None:
+        if self._on_credits_warning:
+            self._on_credits_warning(remaining_percent)
+    
+    def on_credits_critical(self, remaining_percent: int) -> None:
+        if self._on_credits_critical:
+            self._on_credits_critical(remaining_percent)
+    
+    def on_credits_exhausted(self) -> None:
+        if self._on_credits_exhausted:
+            self._on_credits_exhausted()
+    
+    def on_error(self, error: Exception) -> None:
+        if self._on_error:
+            self._on_error(error)
+    
+    def on_close(self, code: int, reason: str) -> None:
+        if self._on_close:
+            self._on_close(code, reason)

orbitalsai/streaming/exceptions.py

@@ -0,0 +1,179 @@
+"""
+OrbitalsAI Streaming Exceptions
+
+Streaming-specific exceptions for the OrbitalsAI SDK.
+"""
+
+from typing import Optional
+
+
+class StreamingError(Exception):
+    """
+    Base exception for all streaming errors.
+    
+    Inherit from this class for streaming-specific exceptions.
+    """
+    pass
+
+
+class ConnectionError(StreamingError):
+    """
+    WebSocket connection errors.
+    
+    Raised when connection fails, drops unexpectedly, or cannot be established.
+    
+    Attributes:
+        code: WebSocket close code (if applicable)
+    """
+    
+    def __init__(self, message: str, code: Optional[int] = None):
+        """
+        Initialize connection error.
+        
+        Args:
+            message: Error description
+            code: WebSocket close code (optional)
+        """
+        super().__init__(message)
+        self.code = code
+    
+    def __str__(self) -> str:
+        if self.code:
+            return f"{super().__str__()} (code: {self.code})"
+        return super().__str__()
+
+
+class AuthenticationError(StreamingError):
+    """
+    Invalid or expired authentication token.
+    
+    Raised when the API key or JWT token is invalid, expired, or doesn't
+    have permission for streaming transcription.
+    """
+    pass
+
+
+class AudioFormatError(StreamingError):
+    """
+    Invalid audio format or encoding.
+    
+    Raised when audio data doesn't meet requirements:
+    - Must be PCM16 mono little-endian
+    - Must have even byte length
+    - Sample rate must be in valid range (8000-48000 Hz)
+    """
+    pass
+
+
+class InsufficientCreditsError(StreamingError):
+    """
+    Insufficient credits for streaming.
+    
+    Raised when the user doesn't have enough credits to start or continue
+    a streaming session.
+    """
+    pass
+
+
+class ReconnectionFailedError(StreamingError):
+    """
+    Failed to reconnect after maximum retries.
+    
+    Raised when all reconnection attempts have been exhausted and the
+    connection could not be restored.
+    
+    Attributes:
+        attempts: Number of reconnection attempts made
+    """
+    
+    def __init__(self, message: str, attempts: int):
+        """
+        Initialize reconnection failed error.
+        
+        Args:
+            message: Error description
+            attempts: Number of reconnection attempts made
+        """
+        super().__init__(message)
+        self.attempts = attempts
+    
+    def __str__(self) -> str:
+        return f"{super().__str__()} (attempts: {self.attempts})"
+
+
+class ServiceUnavailableError(StreamingError):
+    """
+    Transcription service is unavailable.
+    
+    Raised when the backend service (Triton) is not available or unhealthy.
+    This is typically a temporary condition that may resolve with retry.
+    """
+    pass
+
+
+class ServerBusyError(StreamingError):
+    """
+    Server is too busy to accept new connections.
+    
+    Raised when the server has reached its maximum connection limit.
+    Retry after a longer delay.
+    """
+    pass
+
+
+class SessionClosedError(StreamingError):
+    """
+    Operation attempted on a closed session.
+    
+    Raised when trying to send audio or perform operations after the
+    streaming session has been closed.
+    """
+    pass
+
+
+class ProtocolError(StreamingError):
+    """
+    WebSocket protocol error.
+    
+    Raised when receiving invalid or unexpected messages from the server.
+    """
+    pass
+
+
+# Close code mapping for user-friendly error handling
+CLOSE_CODE_ERRORS = {
+    4001: AuthenticationError,
+    4002: ServiceUnavailableError,
+    4003: ServerBusyError,
+    4004: InsufficientCreditsError,
+    4005: InsufficientCreditsError,
+}
+
+
+def exception_from_close_code(code: int, message: str = "") -> StreamingError:
+    """
+    Create appropriate exception from WebSocket close code.
+    
+    Args:
+        code: WebSocket close code
+        message: Optional error message
+        
+    Returns:
+        Appropriate StreamingError subclass instance
+    """
+    error_class = CLOSE_CODE_ERRORS.get(code, ConnectionError)
+    
+    default_messages = {
+        4001: "Authentication failed",
+        4002: "Service unavailable",
+        4003: "Server busy",
+        4004: "Insufficient balance",
+        4005: "Credits exhausted",
+    }
+    
+    if not message:
+        message = default_messages.get(code, f"Connection closed with code {code}")
+    
+    if error_class == ConnectionError:
+        return ConnectionError(message, code=code)
+    return error_class(message)