atom-audio-engine 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

{atom_audio_engine-0.1.4.dist-info → atom_audio_engine-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atom-audio-engine
-Version: 0.1.4
+Version: 0.1.6
 Summary: A pluggable, async-first Python framework for real-time audio-to-audio conversational AI
 Author-email: ATOM Group <info@atomgroup.ng>
 License-Expression: MIT

atom_audio_engine-0.1.6.dist-info/RECORD

@@ -0,0 +1,32 @@
+audio_engine/__init__.py,sha256=KxGAd4of3q5pvGhniSnQvihi-UC-uFI6nFJdbyV2rb8,1538
+audio_engine/asr/__init__.py,sha256=HkNjZXyDqZSYTB17kKp3koI9k5rrjID8kZgH2Idxt28,1232
+audio_engine/asr/base.py,sha256=dC6cvAlxoOzUXNz9do-ueRObmNXqg4rtsY9fh6k67vA,2380
+audio_engine/asr/cartesia.py,sha256=jLoetv6jiAbcfmfGkrwKRGo5sbMZ-WJTwIVvWno1Vko,13185
+audio_engine/asr/deepgram.py,sha256=RwtG0e66Y_8HKehoHFzjgJ5JlQs8JEpu_0kpWGmsvBc,6431
+audio_engine/core/__init__.py,sha256=aqN1HeFZGX0xAnVyfURdExXXxxmwwZEq_KFj6MqXZwo,289
+audio_engine/core/config.py,sha256=Jmp-rr0MXXejF3qtx1-CPCEwQOorggHIH5cV3t8G-I4,5205
+audio_engine/core/pipeline.py,sha256=rMZOlllT32xruz3nkeoYGRfnq94zgs-dzAbTahSITtU,8808
+audio_engine/core/types.py,sha256=iFQPajgeS1YgMWXJvubA8sWbxLI1Z8nF-z1uucrgNm4,2295
+audio_engine/integrations/__init__.py,sha256=69Hna1pfmB929WbM7GpAHlrk4xPOleKTnoaBBksFo9k,114
+audio_engine/integrations/geneface.py,sha256=JgxGYfqDk9n-p4e1VNczoEJdMPzzfF5QGsyxxinrWr8,8790
+audio_engine/llm/__init__.py,sha256=nCMx0QYVZSPVQaqu23LGLE8ePDnceygdw0Zz-4Oqg6g,1016
+audio_engine/llm/base.py,sha256=vsKi2UYuhMr_nubMsoyU6hzSV6gr3DZ1sPvqkSvap3c,2862
+audio_engine/llm/groq.py,sha256=zX4z_ZPyB5_FxhMwg-MnK5Ga6vpqRJLaRTrknSYJZXU,6682
+audio_engine/pipelines/__init__.py,sha256=Q1iZjX38TigrZPBaFgv_5AXw21wBN1Z-4nfXPjV-xDI,49
+audio_engine/pipelines/personaplex/__init__.py,sha256=nX37MS93pYUPKiYwY2aa9G-PEI4x2yKjdLqGeab7wWI,916
+audio_engine/pipelines/personaplex/client.py,sha256=NAiG6V9nTWh8ozrb5jT-6h8fesTuJZDgh-l7DlHQm6M,8667
+audio_engine/pipelines/personaplex/config.py,sha256=6fBteI-HjJJl3ZcK5QZCCa9kcKVNDgPptLIkJNZc9kg,2935
+audio_engine/pipelines/personaplex/pipeline.py,sha256=WUkFalPQ9sxICeFpF-58HJxzfQ30vfZ4WAs-E5aI60s,10411
+audio_engine/pipelines/personaplex/types.py,sha256=6MvU2hBukBflJxat3MtC6bGQY1b33jaOIiOi2tZJRnU,4727
+audio_engine/pipelines/personaplex/utils.py,sha256=um_7nGRFH0QaLIIfLwPnBXgFW0fVGU7gkjF8Gm-Hq4U,5000
+audio_engine/streaming/__init__.py,sha256=0FOorloUtads4ZeJKLdlTcqaL0l2G7Byq4ijQG3W1Fk,127
+audio_engine/streaming/websocket_server.py,sha256=p9_ugvXfUW0TeuCkTCTUoHCmQ0vBTGq2J2Ubys1HdeY,10896
+audio_engine/tts/__init__.py,sha256=sJIN_PgwO1_GVtr6NBR8oegqzLa9oR_qqD6ixbkDVro,967
+audio_engine/tts/base.py,sha256=YbvdVF9XbJyv7NWf_5W7bawyquz8z83BcNcXOdA6iaY,4424
+audio_engine/tts/cartesia.py,sha256=VipeNLgOac_hlsi2hasZe_ALYZZ7hvQ72eFeY17J600,16313
+audio_engine/utils/__init__.py,sha256=J-XxXjgjAmvsM39W3pKI2we-C6S7rd49zfaEf9omwN8,245
+audio_engine/utils/audio.py,sha256=RHp-FRjyCMPDaSQCOnxp7m_KO2z3Enu3iX7J5BVRD-0,5507
+atom_audio_engine-0.1.6.dist-info/METADATA,sha256=C3C3SOBD6B-PSEeFVN5Mn67_1hcGFsIOG5jcNs9YxDI,6690
+atom_audio_engine-0.1.6.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+atom_audio_engine-0.1.6.dist-info/top_level.txt,sha256=IyumwgFrsDL7nlZlBijX-0shiSVhhBCFPUNBRNKzWP4,13
+atom_audio_engine-0.1.6.dist-info/RECORD,,

audio_engine/__init__.py

@@ -4,7 +4,7 @@ Audio Engine - Pluggable audio-to-audio conversational AI framework.
 Orchestrates ASR → LLM → TTS pipeline with real-time streaming support.
 """
 
-__version__ = "0.1.4"
+__version__ = "0.1.6"
 
 # Core exports
 from .core.pipeline import Pipeline
@@ -33,7 +33,11 @@ except ImportError:
 
 # LLM Providers
 from .llm.base import BaseLLM
-from .llm.groq import GroqLLM
+
+try:
+    from .llm.groq import GroqLLM
+except ImportError:
+    pass
 
 # TTS Providers
 from .tts.base import BaseTTS

audio_engine/asr/__init__.py

@@ -0,0 +1,48 @@
+"""ASR (Speech-to-Text) providers."""
+
+from ..core.config import ASRConfig
+
+from .base import BaseASR
+from .cartesia import CartesiaASR
+
+try:
+    from .deepgram import DeepgramASR
+except ImportError:
+    pass
+
+__all__ = ["BaseASR", "DeepgramASR", "CartesiaASR", "get_asr_from_config"]
+
+
+def get_asr_from_config(config: ASRConfig) -> BaseASR:
+    """
+    Instantiate ASR provider from config.
+
+    Args:
+        config: ASRConfig object with provider name and settings
+
+    Returns:
+        Initialized BaseASR provider instance
+
+    Raises:
+        ValueError: If provider name is not recognized
+    """
+    provider_name = config.provider.lower()
+
+    if provider_name == "deepgram":
+        return DeepgramASR(
+            api_key=config.api_key,
+            model=config.model or "nova-2",
+            language=config.language,
+            **config.extra,
+        )
+    elif provider_name == "cartesia":
+        return CartesiaASR(
+            api_key=config.api_key,
+            model=config.model or "ink-whisper",
+            language=config.language,
+            **config.extra,
+        )
+    else:
+        raise ValueError(
+            f"Unknown ASR provider: {config.provider}. " f"Supported: deepgram, cartesia"
+        )

audio_engine/asr/base.py

@@ -0,0 +1,89 @@
+"""Abstract base class for ASR (Speech-to-Text) providers."""
+
+from abc import ABC, abstractmethod
+from typing import AsyncIterator, Optional
+
+from ..core.types import AudioChunk, TranscriptChunk
+
+
+class BaseASR(ABC):
+    """
+    Abstract base class for Speech-to-Text providers.
+
+    All ASR implementations must inherit from this class and implement
+    the required methods for both batch and streaming transcription.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **kwargs):
+        """
+        Initialize the ASR provider.
+
+        Args:
+            api_key: API key for the provider (if required)
+            **kwargs: Additional provider-specific configuration
+        """
+        self.api_key = api_key
+        self.config = kwargs
+
+    @abstractmethod
+    async def transcribe(self, audio: bytes, sample_rate: int = 16000) -> str:
+        """
+        Transcribe a complete audio buffer to text.
+
+        Args:
+            audio: Raw audio bytes (PCM format expected)
+            sample_rate: Sample rate of the audio in Hz
+
+        Returns:
+            Transcribed text string
+        """
+        pass
+
+    @abstractmethod
+    async def transcribe_stream(
+        self, audio_stream: AsyncIterator[AudioChunk]
+    ) -> AsyncIterator[TranscriptChunk]:
+        """
+        Transcribe streaming audio in real-time.
+
+        Args:
+            audio_stream: Async iterator yielding AudioChunk objects
+
+        Yields:
+            TranscriptChunk objects with partial and final transcriptions
+        """
+        pass
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.disconnect()
+
+    async def connect(self):
+        """
+        Establish connection to the ASR service.
+        Override in subclasses if needed.
+        """
+        pass
+
+    async def disconnect(self):
+        """
+        Close connection to the ASR service.
+        Override in subclasses if needed.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Return the name of this ASR provider."""
+        pass
+
+    @property
+    def supports_streaming(self) -> bool:
+        """Whether this provider supports real-time streaming."""
+        return True

audio_engine/asr/cartesia.py

@@ -0,0 +1,350 @@
+"""Cartesia API implementation for ASR (Speech-to-Text) via WebSocket."""
+
+import asyncio
+import json
+import logging
+from typing import AsyncIterator, Optional
+from urllib.parse import quote
+
+import websockets
+
+from ..core.types import AudioChunk, TranscriptChunk
+from .base import BaseASR
+
+logger = logging.getLogger(__name__)
+
+# Cartesia API version (required header)
+CARTESIA_VERSION = "2025-04-16"
+
+
+class CartesiaASR(BaseASR):
+    """
+    Cartesia API client for speech-to-text transcription via WebSocket.
+
+    Supports both batch transcription and real-time streaming.
+    Uses Cartesia's Whisper model (ink-whisper) for high-accuracy transcription.
+
+    Approach:
+    1. Batch mode: collect audio, send via WebSocket, wait for final result
+    2. Streaming mode: send audio chunks as they arrive, yield results immediately
+    3. Background receive task queues responses from server
+    4. VAD (Voice Activity Detection) configurable via min_volume and max_silence_duration_secs
+
+    Example:
+        asr = CartesiaASR(api_key="sk_...")
+
+        # Batch transcription
+        text = await asr.transcribe(audio_bytes)
+
+        # Streaming transcription
+        async for chunk in asr.transcribe_stream(audio_stream):
+            print(chunk.text, end="", flush=True)
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: str = "ink-whisper",
+        language: str = "en",
+        encoding: str = "pcm_s16le",
+        sample_rate: int = 16000,
+        min_volume: float = 0.0,
+        max_silence_duration_secs: float = 30.0,
+        **kwargs,
+    ):
+        """
+        Initialize Cartesia ASR provider.
+
+        Args:
+            api_key: Cartesia API key
+            model: Model to use (default: ink-whisper)
+            language: Language code in ISO-639-1 format (default: en)
+            encoding: Audio encoding format (default: pcm_s16le)
+            sample_rate: Sample rate in Hz (default: 16000)
+            min_volume: VAD threshold 0.0-1.0, higher = more aggressive (default: 0.0)
+            max_silence_duration_secs: Max silence before endpointing (default: 30.0)
+            **kwargs: Additional config (stored in self.config)
+        """
+        super().__init__(api_key=api_key, **kwargs)
+        self.model = model
+        self.language = language
+        self.encoding = encoding
+        self.sample_rate = sample_rate
+        self.min_volume = min_volume
+        self.max_silence_duration_secs = max_silence_duration_secs
+
+        self.websocket = None
+        self._receive_task: Optional[asyncio.Task] = None
+        self._response_queue: asyncio.Queue = asyncio.Queue()
+
+    @property
+    def name(self) -> str:
+        """Return provider name."""
+        return "cartesia"
+
+    async def connect(self):
+        """
+        Initialize WebSocket connection to Cartesia STT endpoint.
+
+        Approach:
+        1. Construct WebSocket URL with parameters (model, language, encoding, sample_rate, VAD)
+        2. Connect to wss://api.cartesia.ai/stt/websocket
+        3. Launch background receive task to collect server responses
+        4. Log initialization status
+
+        Rationale: Lazy connection on first transcription; background task ensures
+        responses are queued even if caller is temporarily blocked.
+        """
+        if self.websocket:
+            return
+
+        try:
+            if not self.api_key:
+                # Try to get from environment
+                import os
+
+                self.api_key = os.getenv("CARTESIA_API_KEY") or os.getenv("ASR_API_KEY")
+
+            if not self.api_key:
+                raise ValueError("Cartesia API key not provided")
+
+            # Construct WebSocket URL with properly encoded parameters
+            # API key must be URL-encoded to handle special characters
+            url = (
+                f"wss://api.cartesia.ai/stt/websocket?"
+                f"model={quote(str(self.model))}"
+                f"&language={quote(str(self.language))}"
+                f"&encoding={quote(str(self.encoding))}"
+                f"&sample_rate={quote(str(self.sample_rate))}"
+                f"&min_volume={quote(str(self.min_volume))}"
+                f"&max_silence_duration_secs={quote(str(self.max_silence_duration_secs))}"
+                f"&api_key={quote(str(self.api_key))}"
+            )
+            logger.debug(f"Cartesia WebSocket URL: {url}")
+
+            # Connect to WebSocket with required Cartesia-Version header
+            try:
+                # Build URL with all parameters
+                # Add Cartesia-Version header via subprotocol or connection params
+                self.websocket = await asyncio.wait_for(
+                    websockets.connect(
+                        url, additional_headers=[("Cartesia-Version", CARTESIA_VERSION)]
+                    ),
+                    timeout=30.0,  # Increase timeout to 30s for initial connection
+                )
+                logger.debug("Cartesia WebSocket connected")
+            except asyncio.TimeoutError:
+                logger.error(f"WebSocket connection timeout to {url}")
+                raise TimeoutError("Failed to connect to Cartesia WebSocket within 30s timeout")
+
+            # Start background receive task
+            self._receive_task = asyncio.create_task(self._receive_loop())
+
+        except Exception as e:
+            logger.error(f"Failed to initialize Cartesia WebSocket: {e}")
+            raise
+
+    async def disconnect(self):
+        """Close WebSocket connection and cleanup."""
+        try:
+            if self._receive_task:
+                self._receive_task.cancel()
+                try:
+                    await self._receive_task
+                except asyncio.CancelledError:
+                    pass
+
+            if self.websocket:
+                await self.websocket.close()
+                logger.debug("Cartesia WebSocket closed")
+
+        except Exception as e:
+            logger.error(f"Error disconnecting Cartesia: {e}")
+
+    async def _receive_loop(self):
+        """
+        Background task: continuously receive messages from WebSocket.
+
+        Parses JSON responses and queues them for retrieval by transcribe methods.
+        Handles: transcript, flush_done, done, error message types.
+        """
+        try:
+            if not self.websocket:
+                return
+
+            async for message in self.websocket:
+                try:
+                    # Parse JSON response
+                    response = json.loads(message)
+                    await self._response_queue.put(response)
+
+                except json.JSONDecodeError as e:
+                    logger.error(f"Failed to parse Cartesia response: {e}")
+                except Exception as e:
+                    logger.error(f"Error in receive loop: {e}")
+
+        except asyncio.CancelledError:
+            logger.debug("Receive loop cancelled")
+        except Exception as e:
+            logger.error(f"Unexpected error in receive loop: {e}")
+
+    async def transcribe(self, audio: bytes, sample_rate: int = 16000) -> str:
+        """
+        Transcribe complete audio buffer to text.
+
+        Approach:
+        1. Initialize WebSocket if needed
+        2. Send audio in chunks (100ms intervals)
+        3. Send 'done' command to finalize
+        4. Collect all responses until 'done' received
+        5. Extract and return transcript text
+
+        Rationale: Batch mode for complete audio files; simple sequential flow.
+
+        Args:
+            audio: Raw PCM audio bytes
+            sample_rate: Sample rate in Hz (default 16000)
+
+        Returns:
+            Transcribed text
+        """
+        if not self.websocket:
+            await self.connect()
+
+        try:
+            logger.debug(f"Transcribing {len(audio)} bytes at {sample_rate}Hz")
+
+            # Send audio in chunks (100ms intervals at 16kHz = 3200 bytes)
+            chunk_size = int(self.sample_rate * 0.1 * 2)  # 100ms in bytes
+            offset = 0
+
+            while offset < len(audio):
+                chunk = audio[offset : offset + chunk_size]
+                await self.websocket.send(chunk)
+                offset += chunk_size
+
+            # Send 'done' command to finalize
+            await self.websocket.send("done")
+
+            # Collect responses until 'done' received
+            transcript_parts = []
+            while True:
+                try:
+                    response = await asyncio.wait_for(self._response_queue.get(), timeout=10.0)
+
+                    if response.get("type") == "transcript":
+                        text = response.get("text", "")
+                        if text:
+                            transcript_parts.append(text)
+
+                    elif response.get("type") == "done":
+                        break
+
+                    elif response.get("type") == "error":
+                        error_msg = response.get("error", "Unknown error")
+                        raise RuntimeError(f"Cartesia error: {error_msg}")
+
+                except asyncio.TimeoutError:
+                    logger.warning("Timeout waiting for Cartesia response")
+                    break
+
+            return "".join(transcript_parts)
+
+        except Exception as e:
+            logger.error(f"Cartesia transcription error: {e}")
+            raise
+
+    async def transcribe_stream(
+        self, audio_stream: AsyncIterator[AudioChunk]
+    ) -> AsyncIterator[TranscriptChunk]:
+        """
+        Transcribe streaming audio in real-time.
+
+        Approach:
+        1. Initialize WebSocket if needed
+        2. For each audio chunk from stream:
+           - Send binary audio via WebSocket
+           - Check response queue for server responses (non-blocking)
+           - Yield TranscriptChunk for each response
+        3. On final audio chunk (is_final=True), send 'done' command
+        4. Continue yielding responses until 'done' received
+        5. Signal stream end
+
+        Rationale: Streaming yields results immediately; low latency;
+        background task queues responses so we don't block on receives.
+
+        Args:
+            audio_stream: Async iterator yielding AudioChunk objects
+
+        Yields:
+            TranscriptChunk objects with partial and final transcriptions
+        """
+        if not self.websocket:
+            await self.connect()
+
+        try:
+            done_sent = False
+
+            async for audio_chunk in audio_stream:
+                # Send audio via WebSocket
+                await self.websocket.send(audio_chunk.data)
+
+                # Try to get responses (non-blocking)
+                while not self._response_queue.empty():
+                    response = self._response_queue.get_nowait()
+
+                    if response.get("type") == "transcript":
+                        text = response.get("text", "")
+                        is_final = response.get("is_final", False)
+                        if text:
+                            yield TranscriptChunk(
+                                text=text,
+                                confidence=None,  # Cartesia doesn't return confidence
+                                is_final=is_final,
+                            )
+
+                    elif response.get("type") == "error":
+                        error_msg = response.get("error", "Unknown error")
+                        logger.error(f"Cartesia error: {error_msg}")
+
+                # If this is the final audio chunk, send 'done' command
+                if audio_chunk.is_final and not done_sent:
+                    await self.websocket.send("done")
+                    done_sent = True
+
+            # Continue collecting responses until 'done' received
+            if done_sent:
+                while True:
+                    try:
+                        response = await asyncio.wait_for(self._response_queue.get(), timeout=5.0)
+
+                        if response.get("type") == "transcript":
+                            text = response.get("text", "")
+                            is_final = response.get("is_final", False)
+                            if text:
+                                yield TranscriptChunk(
+                                    text=text,
+                                    confidence=None,
+                                    is_final=is_final,
+                                )
+
+                        elif response.get("type") == "done":
+                            # Yield final chunk to signal stream end
+                            yield TranscriptChunk(
+                                text="",
+                                confidence=None,
+                                is_final=True,
+                            )
+                            break
+
+                        elif response.get("type") == "error":
+                            error_msg = response.get("error", "Unknown error")
+                            logger.error(f"Cartesia error: {error_msg}")
+
+                    except asyncio.TimeoutError:
+                        logger.warning("Timeout waiting for Cartesia final response")
+                        break
+
+        except Exception as e:
+            logger.error(f"Cartesia streaming transcription error: {e}")
+            raise