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

audio_engine/asr/deepgram.py

@@ -1,196 +0,0 @@
-"""Deepgram API implementation for ASR (Speech-to-Text)."""
-
-import logging
-from typing import AsyncIterator, Optional
-
-from deepgram import DeepgramClient
-
-from core.types import AudioChunk, TranscriptChunk
-from .base import BaseASR
-
-logger = logging.getLogger(__name__)
-
-
-class DeepgramASR(BaseASR):
-    """
-    Deepgram API client for speech-to-text transcription.
-
-    Supports both batch transcription and real-time streaming.
-    Outputs high-accuracy transcripts using Deepgram's Nova-2 model by default.
-
-    Example:
-        asr = DeepgramASR(api_key="dg_...")
-
-        # 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 = "nova-2",
-        language: str = "en",
-        **kwargs,
-    ):
-        """
-        Initialize Deepgram ASR provider.
-
-        Args:
-            api_key: Deepgram API key
-            model: Model to use (e.g., "nova-2", "nova", "enhanced")
-            language: Language code (e.g., "en", "es", "fr")
-            **kwargs: Additional config (stored in self.config)
-        """
-        super().__init__(api_key=api_key, **kwargs)
-        self.model = model
-        self.language = language
-        self.client = None
-
-    @property
-    def name(self) -> str:
-        """Return provider name."""
-        return "deepgram"
-
-    async def connect(self):
-        """
-        Initialize Deepgram client.
-
-        Approach:
-        1. Create client with API key (from param or env var DEEPGRAM_API_KEY)
-        2. Log initialization status
-
-        Rationale: Client reuse for multiple transcription requests.
-        """
-        try:
-            if self.api_key:
-                self.client = DeepgramClient(api_key=self.api_key)
-            else:
-                # Fallback to env var DEEPGRAM_API_KEY
-                self.client = DeepgramClient()
-
-            logger.debug("Deepgram client initialized")
-        except Exception as e:
-            logger.error(f"Failed to initialize Deepgram client: {e}")
-            raise
-
-    async def disconnect(self):
-        """Close Deepgram client connection."""
-        if self.client:
-            try:
-                pass
-            except Exception as e:
-                logger.error(f"Error disconnecting Deepgram: {e}")
-
-    async def transcribe(self, audio: bytes, sample_rate: int = 16000) -> str:
-        """
-        Transcribe complete audio buffer to text.
-
-        Approach:
-        1. Initialize client if needed
-        2. Send audio to Deepgram prerecorded API
-        3. Extract and return transcript text
-
-        Rationale: Batch mode for complete audio files with standard latency.
-
-        Args:
-            audio: Raw PCM audio bytes
-            sample_rate: Sample rate in Hz (default 16000)
-
-        Returns:
-            Transcribed text
-        """
-        if not self.client:
-            await self.connect()
-
-        try:
-            logger.debug(f"Transcribing {len(audio)} bytes at {sample_rate}Hz")
-
-            # Call Deepgram API - using synchronous client
-            response = self.client.listen.prerecorded.v(
-                {
-                    "model": self.model,
-                    "language": self.language,
-                    "encoding": "linear16",
-                    "sample_rate": sample_rate,
-                }
-            ).transcribe_file({"buffer": audio})
-
-            # Extract transcript
-            if response and response.results:
-                if response.results.channels:
-                    channel = response.results.channels[0]
-                    if channel.alternatives:
-                        transcript = channel.alternatives[0].transcript
-                        logger.debug(f"Transcribed to: {transcript[:100]}...")
-                        return transcript
-
-            return ""
-
-        except Exception as e:
-            logger.error(f"Deepgram transcription error: {e}")
-            raise
-
-    async def transcribe_stream(
-        self, audio_stream: AsyncIterator[AudioChunk]
-    ) -> AsyncIterator[TranscriptChunk]:
-        """
-        Transcribe streaming audio in real-time.
-
-        Approach:
-        1. Collect audio chunks from stream until is_final flag
-        2. Send buffered audio to Deepgram API
-        3. Yield transcription results
-
-        Rationale: Simple buffering approach; Deepgram SDK doesn't expose
-        native streaming in current version, so we batch on is_final signals.
-
-        Args:
-            audio_stream: Async iterator yielding AudioChunk objects
-
-        Yields:
-            TranscriptChunk objects with partial and final transcriptions
-        """
-        if not self.client:
-            await self.connect()
-
-        try:
-            buffer = bytearray()
-
-            async for chunk in audio_stream:
-                buffer.extend(chunk.data)
-
-                if chunk.is_final:
-                    # Transcribe accumulated buffer
-                    if buffer:
-                        response = self.client.listen.prerecorded.v(
-                            {
-                                "model": self.model,
-                                "language": self.language,
-                                "encoding": "linear16",
-                                "sample_rate": 16000,
-                            }
-                        ).transcribe_file({"buffer": bytes(buffer)})
-
-                        if response and response.results:
-                            if response.results.channels:
-                                channel = response.results.channels[0]
-                                if channel.alternatives:
-                                    transcript = channel.alternatives[0].transcript
-
-                                    yield TranscriptChunk(
-                                        text=transcript,
-                                        is_final=True,
-                                        confidence=getattr(
-                                            channel.alternatives[0], "confidence", None
-                                        ),
-                                    )
-
-                        buffer = bytearray()
-
-        except Exception as e:
-            logger.error(f"Deepgram streaming error: {e}")
-            raise

audio_engine/core/__init__.py

@@ -1,13 +0,0 @@
-"""Core pipeline and configuration."""
-
-from core.pipeline import Pipeline
-from core.config import AudioEngineConfig
-from core.types import AudioChunk, TranscriptChunk, ResponseChunk
-
-__all__ = [
-    "Pipeline",
-    "AudioEngineConfig",
-    "AudioChunk",
-    "TranscriptChunk",
-    "ResponseChunk",
-]

audio_engine/core/config.py

@@ -1,162 +0,0 @@
-"""Configuration management for the audio engine."""
-
-from dataclasses import dataclass, field
-from typing import Optional, Any
-
-# Provider defaults
-DEFAULT_ASR_PROVIDER = "cartesia"
-DEFAULT_LLM_PROVIDER = "groq"
-DEFAULT_TTS_PROVIDER = "cartesia"
-
-
-@dataclass
-class ASRConfig:
-    """Configuration for ASR (Speech-to-Text) provider."""
-
-    provider: str = DEFAULT_ASR_PROVIDER  # deepgram, etc.
-    api_key: Optional[str] = None
-    model: Optional[str] = None
-    language: str = "en"
-    extra: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class LLMConfig:
-    """Configuration for LLM provider."""
-
-    provider: str = DEFAULT_LLM_PROVIDER  # groq, etc.
-    api_key: Optional[str] = None
-    model: str = "llama-3.1-8b-instant"
-    temperature: float = 0.7
-    max_tokens: int = 1024
-    system_prompt: Optional[str] = None
-    extra: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class TTSConfig:
-    """Configuration for TTS (Text-to-Speech) provider."""
-
-    provider: str = DEFAULT_TTS_PROVIDER  # cartesia, etc.
-    api_key: Optional[str] = None
-    voice_id: Optional[str] = None
-    model: Optional[str] = None
-    speed: float = 1.0
-    extra: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class StreamingConfig:
-    """Configuration for streaming/WebSocket server."""
-
-    host: str = "0.0.0.0"
-    port: int = 8765
-    chunk_size_ms: int = 100  # Audio chunk size in milliseconds
-    buffer_size: int = 4096
-    timeout_seconds: float = 30.0
-
-
-@dataclass
-class GeneFaceConfig:
-    """Configuration for GeneFace++ integration."""
-
-    enabled: bool = False
-    model_path: Optional[str] = None
-    output_resolution: tuple[int, int] = (512, 512)
-    fps: int = 25
-
-
-@dataclass
-class AudioEngineConfig:
-    """Main configuration for the audio engine."""
-
-    asr: ASRConfig = field(default_factory=ASRConfig)
-    llm: LLMConfig = field(default_factory=LLMConfig)
-    tts: TTSConfig = field(default_factory=TTSConfig)
-    streaming: StreamingConfig = field(default_factory=StreamingConfig)
-    geneface: GeneFaceConfig = field(default_factory=GeneFaceConfig)
-
-    # Global settings
-    debug: bool = False
-    log_level: str = "INFO"
-
-    @classmethod
-    def from_env(cls) -> "AudioEngineConfig":
-        """
-        Create config from environment variables.
-
-        Supported environment variables:
-        - ASR_PROVIDER: ASR provider name (default: deepgram)
-        - ASR_API_KEY: ASR API key (fallback: DEEPGRAM_API_KEY)
-        - LLM_PROVIDER: LLM provider name (default: groq)
-        - LLM_API_KEY: LLM API key (fallback: GROQ_API_KEY)
-        - LLM_MODEL: LLM model name (default: llama-3.1-8b-instant)
-        - TTS_PROVIDER: TTS provider name (default: cartesia)
-        - TTS_API_KEY: TTS API key (fallback: CARTESIA_API_KEY)
-        - TTS_VOICE_ID: TTS voice identifier
-        - DEBUG: Enable debug mode (default: false)
-        """
-        import os
-
-        return cls(
-            asr=ASRConfig(
-                provider=os.getenv("ASR_PROVIDER", DEFAULT_ASR_PROVIDER),
-                api_key=os.getenv("ASR_API_KEY")
-                or os.getenv("CARTESIA_API_KEY")
-                or os.getenv("DEEPGRAM_API_KEY"),
-            ),
-            llm=LLMConfig(
-                provider=os.getenv("LLM_PROVIDER", DEFAULT_LLM_PROVIDER),
-                api_key=os.getenv("LLM_API_KEY") or os.getenv("GROQ_API_KEY"),
-                model=os.getenv("LLM_MODEL", "llama-3.1-8b-instant"),
-            ),
-            tts=TTSConfig(
-                provider=os.getenv("TTS_PROVIDER", DEFAULT_TTS_PROVIDER),
-                api_key=os.getenv("TTS_API_KEY") or os.getenv("CARTESIA_API_KEY"),
-                voice_id=os.getenv("TTS_VOICE_ID"),
-            ),
-            debug=os.getenv("DEBUG", "false").lower() == "true",
-        )
-
-    @classmethod
-    def from_dict(cls, data: dict) -> "AudioEngineConfig":
-        """Create config from a dictionary."""
-        return cls(
-            asr=ASRConfig(**data.get("asr", {})),
-            llm=LLMConfig(**data.get("llm", {})),
-            tts=TTSConfig(**data.get("tts", {})),
-            streaming=StreamingConfig(**data.get("streaming", {})),
-            geneface=GeneFaceConfig(**data.get("geneface", {})),
-            debug=data.get("debug", False),
-            log_level=data.get("log_level", "INFO"),
-        )
-
-    def create_pipeline(self, system_prompt: Optional[str] = None) -> "Pipeline":
-        """
-        Create a Pipeline instance from this config.
-
-        Args:
-            system_prompt: Optional system prompt override
-
-        Returns:
-            Initialized Pipeline with providers
-
-        Raises:
-            ValueError: If provider initialization fails
-        """
-        from asr import get_asr_from_config
-        from llm import get_llm_from_config
-        from tts import get_tts_from_config
-        from core.pipeline import Pipeline
-
-        asr = get_asr_from_config(self.asr)
-        llm = get_llm_from_config(self.llm)
-        tts = get_tts_from_config(self.tts)
-
-        return Pipeline(
-            asr=asr,
-            llm=llm,
-            tts=tts,
-            system_prompt=system_prompt or self.llm.system_prompt,
-            debug=self.debug,
-        )

audio_engine/core/pipeline.py

@@ -1,282 +0,0 @@
-"""Main pipeline orchestrator for audio-to-audio conversation."""
-
-import asyncio
-import logging
-import time
-from typing import AsyncIterator, Optional, Callable, Any
-
-from asr.base import BaseASR
-from llm.base import BaseLLM
-from tts.base import BaseTTS
-from core.types import (
-    AudioChunk,
-    TranscriptChunk,
-    ResponseChunk,
-    ConversationContext,
-)
-
-logger = logging.getLogger(__name__)
-
-
-class Pipeline:
-    """
-    Main orchestrator for the audio-to-audio conversational pipeline.
-
-    Coordinates the flow: Audio Input → ASR → LLM → TTS → Audio Output
-
-    Example:
-        ```python
-        pipeline = Pipeline(
-            asr=WhisperASR(api_key="..."),
-            llm=AnthropicLLM(api_key="...", model="claude-sonnet-4-20250514"),
-            tts=CartesiaTTS(api_key="...", voice_id="...")
-        )
-
-        # Simple usage
-        response_audio = await pipeline.process(input_audio_bytes)
-
-        # Streaming usage
-        async for chunk in pipeline.stream(audio_stream):
-            play_audio(chunk)
-        ```
-    """
-
-    def __init__(
-        self,
-        asr: BaseASR,
-        llm: BaseLLM,
-        tts: BaseTTS,
-        system_prompt: Optional[str] = None,
-        on_transcript: Optional[Callable[[str], Any]] = None,
-        on_llm_response: Optional[Callable[[str], Any]] = None,
-        debug: bool = False,
-    ):
-        """
-        Initialize the pipeline with providers.
-
-        Args:
-            asr: Speech-to-Text provider instance
-            llm: Language model provider instance
-            tts: Text-to-Speech provider instance
-            system_prompt: System prompt for the LLM
-            on_transcript: Callback when transcript is ready
-            on_llm_response: Callback when LLM response is ready
-            debug: Enable debug logging
-        """
-        self.asr = asr
-        self.llm = llm
-        self.tts = tts
-
-        self.context = ConversationContext(system_prompt=system_prompt)
-        self.on_transcript = on_transcript
-        self.on_llm_response = on_llm_response
-        self.debug = debug
-
-        if debug:
-            logging.basicConfig(level=logging.DEBUG)
-
-        self._is_connected = False
-
-    async def connect(self):
-        """Initialize connections to all providers."""
-        if self._is_connected:
-            return
-
-        await asyncio.gather(
-            self.asr.connect(),
-            self.llm.connect(),
-            self.tts.connect(),
-        )
-        self._is_connected = True
-        logger.info("Pipeline connected to all providers")
-
-    async def disconnect(self):
-        """Close connections to all providers."""
-        if not self._is_connected:
-            return
-
-        await asyncio.gather(
-            self.asr.disconnect(),
-            self.llm.disconnect(),
-            self.tts.disconnect(),
-        )
-        self._is_connected = False
-        logger.info("Pipeline disconnected from all providers")
-
-    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 process(self, audio: bytes, sample_rate: int = 16000) -> bytes:
-        """
-        Process audio input and return complete audio response.
-
-        This is the simple, non-streaming interface. Use `stream()` for
-        lower latency.
-
-        Args:
-            audio: Input audio bytes (PCM format)
-            sample_rate: Sample rate of input audio
-
-        Returns:
-            Response audio bytes
-        """
-        start_time = time.time()
-
-        # Step 1: ASR - Transcribe audio to text
-        transcript = await self.asr.transcribe(audio, sample_rate)
-        asr_time = time.time() - start_time
-        logger.debug(f"ASR completed in {asr_time:.2f}s: {transcript[:50]}...")
-
-        if self.on_transcript:
-            self.on_transcript(transcript)
-
-        # Add user message to context
-        self.context.add_message("user", transcript)
-
-        # Step 2: LLM - Generate response
-        llm_start = time.time()
-        response_text = await self.llm.generate(transcript, self.context)
-        llm_time = time.time() - llm_start
-        logger.debug(f"LLM completed in {llm_time:.2f}s: {response_text[:50]}...")
-
-        if self.on_llm_response:
-            self.on_llm_response(response_text)
-
-        # Add assistant message to context
-        self.context.add_message("assistant", response_text)
-
-        # Step 3: TTS - Synthesize response to audio
-        tts_start = time.time()
-        response_audio = await self.tts.synthesize(response_text)
-        tts_time = time.time() - tts_start
-        logger.debug(f"TTS completed in {tts_time:.2f}s")
-
-        total_time = time.time() - start_time
-        logger.info(
-            f"Pipeline total: {total_time:.2f}s "
-            f"(ASR: {asr_time:.2f}s, LLM: {llm_time:.2f}s, TTS: {tts_time:.2f}s)"
-        )
-
-        return response_audio
-
-    async def stream(
-        self, audio_stream: AsyncIterator[AudioChunk]
-    ) -> AsyncIterator[AudioChunk]:
-        """
-        Process streaming audio input and yield streaming audio output.
-
-        This provides the lowest latency by:
-        1. Streaming ASR transcription
-        2. Streaming LLM generation
-        3. Streaming TTS synthesis
-
-        Args:
-            audio_stream: Async iterator of input AudioChunk objects
-
-        Yields:
-            AudioChunk objects containing response audio
-        """
-        start_time = time.time()
-
-        # Step 1: Stream audio through ASR
-        transcript_buffer = ""
-        async for transcript_chunk in self.asr.transcribe_stream(audio_stream):
-            transcript_buffer += transcript_chunk.text
-            if transcript_chunk.is_final:
-                break
-
-        if not transcript_buffer.strip():
-            return
-
-        asr_time = time.time() - start_time
-        logger.debug(f"ASR streaming completed in {asr_time:.2f}s")
-
-        if self.on_transcript:
-            self.on_transcript(transcript_buffer)
-
-        self.context.add_message("user", transcript_buffer)
-
-        # Step 2: Stream LLM response and pipe to TTS
-        llm_start = time.time()
-        response_buffer = ""
-
-        async def llm_text_stream() -> AsyncIterator[str]:
-            nonlocal response_buffer
-            async for chunk in self.llm.generate_stream(
-                transcript_buffer, self.context
-            ):
-                response_buffer += chunk.text
-                yield chunk.text
-                if chunk.is_final:
-                    break
-
-        # Step 3: Stream TTS audio as LLM generates text
-        first_audio_time = None
-        async for audio_chunk in self.tts.synthesize_stream_text(llm_text_stream()):
-            if first_audio_time is None:
-                first_audio_time = time.time() - start_time
-                logger.debug(f"Time to first audio: {first_audio_time:.2f}s")
-            yield audio_chunk
-
-        llm_time = time.time() - llm_start
-        logger.debug(f"LLM+TTS streaming completed in {llm_time:.2f}s")
-
-        if self.on_llm_response:
-            self.on_llm_response(response_buffer)
-
-        self.context.add_message("assistant", response_buffer)
-
-        total_time = time.time() - start_time
-        logger.info(f"Pipeline streaming total: {total_time:.2f}s")
-
-    async def stream_text_input(self, text: str) -> AsyncIterator[AudioChunk]:
-        """
-        Process text input (skip ASR) and yield streaming audio output.
-
-        Useful for text-based input or when ASR is handled externally.
-
-        Args:
-            text: User's text input
-
-        Yields:
-            AudioChunk objects containing response audio
-        """
-        self.context.add_message("user", text)
-
-        response_buffer = ""
-
-        async def llm_text_stream() -> AsyncIterator[str]:
-            nonlocal response_buffer
-            async for chunk in self.llm.generate_stream(text, self.context):
-                response_buffer += chunk.text
-                yield chunk.text
-
-        async for audio_chunk in self.tts.synthesize_stream_text(llm_text_stream()):
-            yield audio_chunk
-
-        self.context.add_message("assistant", response_buffer)
-
-    def reset_context(self):
-        """Clear conversation history."""
-        self.context.clear()
-        logger.debug("Conversation context cleared")
-
-    def set_system_prompt(self, prompt: str):
-        """Update the system prompt."""
-        self.context.system_prompt = prompt
-        logger.debug("System prompt updated")
-
-    @property
-    def providers(self) -> dict:
-        """Get information about configured providers."""
-        return {
-            "asr": self.asr.name,
-            "llm": self.llm.name,
-            "tts": self.tts.name,
-        }