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

orbitalsai/streaming/config.py

@@ -0,0 +1,207 @@
+"""
+OrbitalsAI Streaming Configuration
+
+Configuration dataclass for streaming transcription sessions.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+import logging
+
+logger = logging.getLogger("orbitalsai.streaming")
+
+
+# Supported languages for streaming transcription
+STREAMING_SUPPORTED_LANGUAGES: List[str] = [
+    "english", "hausa", "igbo", "yoruba"
+]
+
+# Valid sample rate range
+MIN_SAMPLE_RATE = 8000
+MAX_SAMPLE_RATE = 48000
+DEFAULT_SAMPLE_RATE = 16000
+
+# Default chunk size (samples at 16kHz = 500ms)
+DEFAULT_CHUNK_SIZE = 8000
+
+
+@dataclass
+class StreamingConfig:
+    """
+    Configuration for streaming transcription sessions.
+    
+    Attributes:
+        sample_rate: Audio sample rate in Hz (8000-48000, default: 16000)
+        chunk_size: Number of samples per chunk (default: 8000 = 500ms at 16kHz)
+        encoding: Audio encoding format (default: "pcm_s16le")
+        language: Target transcription language (default: "english")
+        auto_detect_language: Whether to auto-detect language (default: False)
+        max_retries: Maximum reconnection attempts (default: 5)
+        retry_delay: Initial retry delay in seconds (default: 1.0)
+        keepalive_interval: WebSocket ping interval in seconds (default: 15.0)
+        connection_timeout: Connection timeout in seconds (default: 30.0)
+        interim_results: Whether to receive partial transcripts (default: True)
+        auto_flush: Whether to auto-flush on silence (default: True)
+    
+    Example:
+        config = StreamingConfig(
+            language="hausa",
+            sample_rate=16000,
+            interim_results=True
+        )
+    """
+    
+    # Audio settings
+    sample_rate: int = DEFAULT_SAMPLE_RATE
+    chunk_size: int = DEFAULT_CHUNK_SIZE
+    encoding: str = "pcm_s16le"
+    
+    # Language settings
+    language: str = "english"
+    auto_detect_language: bool = False
+    
+    # Connection settings
+    max_retries: int = 5
+    retry_delay: float = 1.0
+    max_retry_delay: float = 60.0
+    keepalive_interval: float = 15.0
+    connection_timeout: float = 30.0
+    
+    # Processing settings
+    interim_results: bool = True
+    auto_flush: bool = True
+    
+    def __post_init__(self) -> None:
+        """Validate configuration after initialization."""
+        self.validate()
+    
+    def validate(self) -> None:
+        """
+        Validate configuration values.
+        
+        Raises:
+            ValueError: If any configuration value is invalid
+        """
+        # Validate sample rate
+        if not MIN_SAMPLE_RATE <= self.sample_rate <= MAX_SAMPLE_RATE:
+            raise ValueError(
+                f"sample_rate must be between {MIN_SAMPLE_RATE} and {MAX_SAMPLE_RATE}, "
+                f"got {self.sample_rate}"
+            )
+        
+        # Validate chunk size
+        if self.chunk_size <= 0:
+            raise ValueError(f"chunk_size must be positive, got {self.chunk_size}")
+        
+        # Validate language
+        if self.language.lower() not in STREAMING_SUPPORTED_LANGUAGES:
+            raise ValueError(
+                f"Unsupported language: {self.language}. "
+                f"Supported languages: {', '.join(STREAMING_SUPPORTED_LANGUAGES)}"
+            )
+        
+        # Validate connection settings
+        if self.max_retries < 0:
+            raise ValueError(f"max_retries must be non-negative, got {self.max_retries}")
+        
+        if self.retry_delay <= 0:
+            raise ValueError(f"retry_delay must be positive, got {self.retry_delay}")
+        
+        if self.keepalive_interval <= 0:
+            raise ValueError(f"keepalive_interval must be positive, got {self.keepalive_interval}")
+        
+        if self.connection_timeout <= 0:
+            raise ValueError(f"connection_timeout must be positive, got {self.connection_timeout}")
+        
+        # Validate encoding
+        if self.encoding != "pcm_s16le":
+            logger.warning(
+                f"Only 'pcm_s16le' encoding is currently supported. "
+                f"Got '{self.encoding}', using 'pcm_s16le' instead."
+            )
+            self.encoding = "pcm_s16le"
+    
+    @property
+    def chunk_duration_ms(self) -> float:
+        """
+        Calculate chunk duration in milliseconds.
+        
+        Returns:
+            Duration of one chunk in milliseconds
+        """
+        return (self.chunk_size / self.sample_rate) * 1000
+    
+    @property
+    def bytes_per_chunk(self) -> int:
+        """
+        Calculate bytes per chunk for PCM16 audio.
+        
+        Returns:
+            Number of bytes per chunk (chunk_size * 2 for int16)
+        """
+        return self.chunk_size * 2  # 2 bytes per int16 sample
+    
+    @property
+    def bytes_per_second(self) -> int:
+        """
+        Calculate bytes per second for the configured sample rate.
+        
+        Returns:
+            Number of bytes per second of audio
+        """
+        return self.sample_rate * 2  # 2 bytes per int16 sample
+    
+    def copy(self, **updates) -> 'StreamingConfig':
+        """
+        Create a copy of this config with optional updates.
+        
+        Args:
+            **updates: Fields to update in the copy
+            
+        Returns:
+            New StreamingConfig with updates applied
+        """
+        import copy
+        new_config = copy.copy(self)
+        for key, value in updates.items():
+            if hasattr(new_config, key):
+                setattr(new_config, key, value)
+            else:
+                raise ValueError(f"Unknown config field: {key}")
+        new_config.validate()
+        return new_config
+    
+    def to_dict(self) -> dict:
+        """
+        Convert config to dictionary.
+        
+        Returns:
+            Dictionary representation of config
+        """
+        return {
+            "sample_rate": self.sample_rate,
+            "chunk_size": self.chunk_size,
+            "encoding": self.encoding,
+            "language": self.language,
+            "auto_detect_language": self.auto_detect_language,
+            "max_retries": self.max_retries,
+            "retry_delay": self.retry_delay,
+            "max_retry_delay": self.max_retry_delay,
+            "keepalive_interval": self.keepalive_interval,
+            "connection_timeout": self.connection_timeout,
+            "interim_results": self.interim_results,
+            "auto_flush": self.auto_flush,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> 'StreamingConfig':
+        """
+        Create config from dictionary.
+        
+        Args:
+            data: Dictionary with config values
+            
+        Returns:
+            New StreamingConfig instance
+        """
+        return cls(**{k: v for k, v in data.items() if hasattr(cls, k)})

orbitalsai/streaming/connection.py

@@ -0,0 +1,298 @@
+"""
+OrbitalsAI Streaming Connection Manager
+
+WebSocket connection management with auto-reconnection.
+"""
+
+import asyncio
+import logging
+import random
+import time
+from typing import Callable, Optional
+
+from .protocol import should_retry, get_close_reason, CLOSE_CODES
+from .exceptions import (
+    ConnectionError,
+    ReconnectionFailedError,
+    AuthenticationError,
+    ServiceUnavailableError,
+    ServerBusyError,
+    InsufficientCreditsError,
+)
+
+logger = logging.getLogger("orbitalsai.streaming")
+
+
+def calculate_backoff(
+    attempt: int,
+    base_delay: float = 1.0,
+    max_delay: float = 60.0,
+    jitter: bool = True
+) -> float:
+    """
+    Calculate exponential backoff delay with optional jitter.
+    
+    Args:
+        attempt: Current retry attempt (0-indexed)
+        base_delay: Initial delay in seconds
+        max_delay: Maximum delay in seconds
+        jitter: Whether to add random jitter
+        
+    Returns:
+        Delay in seconds
+    """
+    delay = min(base_delay * (2 ** attempt), max_delay)
+    
+    if jitter:
+        # Add 0-10% jitter
+        jitter_amount = random.uniform(0, delay * 0.1)
+        delay += jitter_amount
+    
+    return delay
+
+
+class ConnectionState:
+    """Connection state enumeration."""
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+    CLOSED = "closed"
+
+
+class ConnectionManager:
+    """
+    Manages WebSocket connection with auto-reconnection.
+    
+    Handles:
+    - Initial connection establishment
+    - Automatic reconnection on connection loss
+    - Exponential backoff with jitter
+    - Close code handling
+    
+    Example:
+        manager = ConnectionManager(
+            max_retries=5,
+            base_delay=1.0,
+            max_delay=60.0
+        )
+        
+        async with manager.connect(ws_url) as ws:
+            await ws.send(data)
+    """
+    
+    def __init__(
+        self,
+        max_retries: int = 5,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        connection_timeout: float = 30.0,
+        on_reconnect: Optional[Callable[[], None]] = None,
+        on_reconnect_failed: Optional[Callable[[int], None]] = None,
+    ):
+        """
+        Initialize connection manager.
+        
+        Args:
+            max_retries: Maximum number of reconnection attempts
+            base_delay: Initial retry delay in seconds
+            max_delay: Maximum retry delay in seconds
+            connection_timeout: Connection timeout in seconds
+            on_reconnect: Callback when reconnection starts
+            on_reconnect_failed: Callback when reconnection fails (receives attempt count)
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.connection_timeout = connection_timeout
+        self.on_reconnect = on_reconnect
+        self.on_reconnect_failed = on_reconnect_failed
+        
+        self._state = ConnectionState.DISCONNECTED
+        self._retry_count = 0
+        self._last_close_code: Optional[int] = None
+        self._last_close_reason: Optional[str] = None
+    
+    @property
+    def state(self) -> str:
+        """Get current connection state."""
+        return self._state
+    
+    @property
+    def is_connected(self) -> bool:
+        """Check if currently connected."""
+        return self._state == ConnectionState.CONNECTED
+    
+    @property
+    def retry_count(self) -> int:
+        """Get current retry count."""
+        return self._retry_count
+    
+    @property
+    def last_close_code(self) -> Optional[int]:
+        """Get last WebSocket close code."""
+        return self._last_close_code
+    
+    @property
+    def last_close_reason(self) -> Optional[str]:
+        """Get last WebSocket close reason."""
+        return self._last_close_reason
+    
+    def reset(self) -> None:
+        """Reset connection state and retry count."""
+        self._state = ConnectionState.DISCONNECTED
+        self._retry_count = 0
+        self._last_close_code = None
+        self._last_close_reason = None
+    
+    def record_close(self, code: int, reason: str = "") -> None:
+        """
+        Record a connection close event.
+        
+        Args:
+            code: WebSocket close code
+            reason: Close reason string
+        """
+        self._last_close_code = code
+        self._last_close_reason = reason or get_close_reason(code)
+        self._state = ConnectionState.DISCONNECTED
+    
+    def should_reconnect(self, close_code: Optional[int] = None) -> bool:
+        """
+        Determine if reconnection should be attempted.
+        
+        Args:
+            close_code: WebSocket close code (uses last recorded if not provided)
+            
+        Returns:
+            True if should attempt reconnection
+        """
+        code = close_code or self._last_close_code
+        
+        if code is None:
+            return True  # Unknown close, try to reconnect
+        
+        # Check if we've exhausted retries
+        if self._retry_count >= self.max_retries:
+            return False
+        
+        # Check if this close code allows retry
+        return should_retry(code)
+    
+    def get_retry_delay(self) -> float:
+        """
+        Get delay before next retry attempt.
+        
+        Uses exponential backoff with jitter.
+        May use longer delays for certain close codes.
+        
+        Returns:
+            Delay in seconds
+        """
+        base = self.base_delay
+        
+        # Use longer base delay for server busy
+        if self._last_close_code == 4003:  # Server busy
+            base = self.base_delay * 2
+        
+        return calculate_backoff(
+            self._retry_count,
+            base_delay=base,
+            max_delay=self.max_delay,
+            jitter=True
+        )
+    
+    async def wait_for_retry(self) -> None:
+        """Wait before retry attempt."""
+        delay = self.get_retry_delay()
+        logger.info(f"Waiting {delay:.1f}s before retry attempt {self._retry_count + 1}")
+        await asyncio.sleep(delay)
+    
+    def increment_retry(self) -> int:
+        """
+        Increment retry counter.
+        
+        Returns:
+            New retry count
+        """
+        self._retry_count += 1
+        self._state = ConnectionState.RECONNECTING
+        
+        if self.on_reconnect:
+            try:
+                self.on_reconnect()
+            except Exception as e:
+                logger.warning(f"on_reconnect callback error: {e}")
+        
+        return self._retry_count
+    
+    def reset_retry_count(self) -> None:
+        """Reset retry counter (call after successful connection)."""
+        self._retry_count = 0
+    
+    def mark_connected(self) -> None:
+        """Mark connection as established."""
+        self._state = ConnectionState.CONNECTED
+        self.reset_retry_count()
+    
+    def mark_connecting(self) -> None:
+        """Mark connection as in progress."""
+        self._state = ConnectionState.CONNECTING
+    
+    def mark_closed(self) -> None:
+        """Mark connection as permanently closed."""
+        self._state = ConnectionState.CLOSED
+    
+    def raise_for_close_code(self, code: int, reason: str = "") -> None:
+        """
+        Raise appropriate exception for close code.
+        
+        Args:
+            code: WebSocket close code
+            reason: Close reason string
+            
+        Raises:
+            Appropriate exception for the close code
+        """
+        self.record_close(code, reason)
+        
+        reason = reason or get_close_reason(code)
+        
+        if code == 4001:
+            raise AuthenticationError(reason)
+        elif code == 4002:
+            raise ServiceUnavailableError(reason)
+        elif code == 4003:
+            raise ServerBusyError(reason)
+        elif code in (4004, 4005):
+            raise InsufficientCreditsError(reason)
+        else:
+            raise ConnectionError(reason, code=code)
+    
+    def check_can_reconnect(self) -> None:
+        """
+        Check if reconnection is possible.
+        
+        Raises:
+            ReconnectionFailedError: If max retries exceeded
+            Other exceptions: For non-retryable close codes
+        """
+        if not self.should_reconnect():
+            if self._retry_count >= self.max_retries:
+                if self.on_reconnect_failed:
+                    try:
+                        self.on_reconnect_failed(self._retry_count)
+                    except Exception as e:
+                        logger.warning(f"on_reconnect_failed callback error: {e}")
+                
+                raise ReconnectionFailedError(
+                    f"Failed to reconnect after {self._retry_count} attempts",
+                    attempts=self._retry_count
+                )
+            
+            # Non-retryable close code
+            if self._last_close_code:
+                self.raise_for_close_code(
+                    self._last_close_code,
+                    self._last_close_reason or ""
+                )