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

{atom_audio_engine-0.1.0.dist-info → atom_audio_engine-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atom-audio-engine
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -63,8 +63,13 @@ A pluggable audio-to-audio conversational engine with real-time streaming suppor
 ## Installation
 
 ```bash
-cd /Users/mayowaadebanjo/Projects/audio_engine
-pip install -r requirements.txt
+pip install atom-audio-engine
+```
+
+For development with all optional dependencies:
+
+```bash
+pip install atom-audio-engine[all,dev]
 ```
 
 ## Quick Start
@@ -79,8 +84,8 @@ from audio_engine.tts import CartesiaTTS
 
 # Create pipeline with your providers
 pipeline = Pipeline(
-    asr=WhisperASR(api_key="your-openai-key"),
-    llm=AnthropicLLM(api_key="your-anthropic-key", model="claude-sonnet-4-20250514"),
+    asr=CartesiaASR(api_key="your-cartesia-key"),
+    llm=GroqLLM(api_key="your-groq-key", model="mixtral-8x7b-32768"),
     tts=CartesiaTTS(api_key="your-cartesia-key", voice_id="your-voice-id"),
     system_prompt="You are a helpful assistant.",
 )

atom_audio_engine-0.1.2.dist-info/RECORD

@@ -0,0 +1,57 @@
+audio_engine/__init__.py,sha256=AQ0uto-Jn3cNqW35MMtSyX5mhXJMFv9AQhjcAkqZ7L4,1499
+audio_engine/asr/__init__.py,sha256=w0t2ahxgApZbZjSc748tN3tmKDeXzasfBh51ZjPF9uc,1203
+audio_engine/asr/base.py,sha256=MFC_7HmyEDnhDwUn62CWZsiF9_-mBVVsUK-Yppiq4Vk,2378
+audio_engine/asr/cartesia.py,sha256=BXnvscO9VaR3LsfEGn7lJ66udzUjz44JzZTmSizZqIg,13321
+audio_engine/asr/deepgram.py,sha256=M59lgrVFMS6-3YQcYaUY7cUdt2-MBptt_VExdfnSXr0,6429
+audio_engine/core/__init__.py,sha256=7naTEkqDjrPsejviXk662OR86xVCyckU7eMKVpjwYys,301
+audio_engine/core/config.py,sha256=EF98O2Gt8q29FX3T6UeDwWNIbm77bni99SThiJKl5Tk,5203
+audio_engine/core/pipeline.py,sha256=jX9jAlIfwU6V8GjqjivyK8Y7P41S-QS8xKYv5c9_qG0,8850
+audio_engine/core/types.py,sha256=iFQPajgeS1YgMWXJvubA8sWbxLI1Z8nF-z1uucrgNm4,2295
+audio_engine/examples/__init__.py,sha256=4oFCZaD-vg0o48hnj03ZsktG2JrtwJ7HXUYOwEYSNCY,44
+audio_engine/examples/basic_stt_llm_tts.py,sha256=tw8IIAL0WSG2M9U5SuLri75AOb7YM-twvAVAspaYVQM,6354
+audio_engine/examples/geneface_animation.py,sha256=ogjQAqPHT5EW6X3R8hn0tJwj-_QBbPiBFDZDl_olTGo,2945
+audio_engine/examples/personaplex_pipeline.py,sha256=OcpN8i5qoAS3Nmuc62tESzpRwPxsjxTGTrY_qICLETo,3641
+audio_engine/examples/websocket_server.py,sha256=HhTlAFnJQXJyOs_prwFJASuh6h-0FKEh2JGeJSChf_c,2398
+audio_engine/integrations/__init__.py,sha256=1y4CTaqybOwmfk_xxkWANYkc-A7PgH0JFMZCTq33fe4,126
+audio_engine/integrations/geneface.py,sha256=2oeVZazp2R9gN-YmQhzzrZb87CBpEiAyKA8hHUxUZJk,8788
+audio_engine/llm/__init__.py,sha256=mwr0C1E1Wf5589fVt7emOFMA2fHoXxQ5t-3dOxkXQEI,997
+audio_engine/llm/base.py,sha256=C-ZNOab0Ca-vlxWgnPzB8uZXFNYbPgAYfQLNvaal2KU,2873
+audio_engine/llm/groq.py,sha256=oGSjJBW0TiCmOzzl1HTE8zUhPC78I3ywhAYFq7Te2IA,6694
+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/scripts/debug_pipeline.py,sha256=HkrrVzimrmFsbltbEPKoAuJ_5yzBWBCWyrEH0_ZHOQM,2276
+audio_engine/scripts/debug_tts.py,sha256=Aj-vW8kmcR7lDa2FdTn1_6wrFw1vpP8Kjnh1rLwQ_ag,4479
+audio_engine/scripts/test_cartesia_connect.py,sha256=KoaBWxmfzdMBqpnDXwT2fFzAJsJlKg3hMsUYvAeU-L8,1529
+audio_engine/streaming/__init__.py,sha256=Pd_ICcYeW75DXMsFpMrJnn9N-RU5s1_Wb3WZ3YbOTC4,136
+audio_engine/streaming/websocket_server.py,sha256=miqHoVkUjznpmpQQrgkyaURR6DsDJLzkP_OGrBFOBYk,10994
+audio_engine/tests/__init__.py,sha256=1JoGYWcW0zfdTZAgxs7NZaK4Zo0zlvq79dXzVwKMP3I,34
+audio_engine/tests/test_personaplex/__init__.py,sha256=1JoGYWcW0zfdTZAgxs7NZaK4Zo0zlvq79dXzVwKMP3I,34
+audio_engine/tests/test_personaplex/test_personaplex.py,sha256=BrYWbWmWqlzdK3H5YZtpLr4DxtK5UeLpbdwUabuUTnE,457
+audio_engine/tests/test_personaplex/test_personaplex_client.py,sha256=RlGNHa-IcKC7CCiTQJDhUYN9HNMun7Q45AsFSu5swZ8,8377
+audio_engine/tests/test_personaplex/test_personaplex_config.py,sha256=c-86tJ81NSfPOk8tIV_JfDn3IcJnFrgCHVqJGyw14lM,2487
+audio_engine/tests/test_personaplex/test_personaplex_message.py,sha256=6gAbQUk954x4-PXkFdNb0GadxuJIJ49tRixPteFCiw4,2636
+audio_engine/tests/test_personaplex/test_personaplex_pipeline.py,sha256=GCvNRgUN72d81RK0klc3z5ecBhBMgf4rJXgq5auXv6M,7424
+audio_engine/tests/test_personaplex/test_personaplex_session.py,sha256=pF2s649MAh0TlRs4ooQBCExN-VSuc_DntknyfLw8Pxw,5780
+audio_engine/tests/test_personaplex/test_personaplex_transcript.py,sha256=XdNAghb1Gjg68BBcj6BPt-1K-6rzS9gD3tufnp8vVPo,6400
+audio_engine/tests/test_traditional_pipeline/__init__.py,sha256=1JoGYWcW0zfdTZAgxs7NZaK4Zo0zlvq79dXzVwKMP3I,34
+audio_engine/tests/test_traditional_pipeline/test_cartesia_asr.py,sha256=rLM_7s-UQJEJGL98A8ewXrgckruog6ei-lFtpPetIkk,15353
+audio_engine/tests/test_traditional_pipeline/test_config_env.py,sha256=pZd0doTKzZg7e_ZwEKLe3pfmZTBdXIlrO1-CUU1lPmc,3192
+audio_engine/tests/test_traditional_pipeline/test_conversation_context.py,sha256=t6lk_5QwGE1CfU1RIAGVIB6d6flfoqVLNgPYs-aE1PA,4049
+audio_engine/tests/test_traditional_pipeline/test_pipeline_creation.py,sha256=U8s4vc36JU79YTFVyv7HQlFN3Hj2KRfh-gWQKhsjiSA,2278
+audio_engine/tests/test_traditional_pipeline/test_pipeline_with_mocks.py,sha256=N5ajn2QevssnP0xEBeR87FumT0w1j7BdVAiMmBLqL2A,5583
+audio_engine/tests/test_traditional_pipeline/test_provider_factories.py,sha256=a9Da5wjhXV6-E_Q7E8AquKxbcTKAhjd2eVKUGBj3zpo,2240
+audio_engine/tests/test_traditional_pipeline/test_websocket_server.py,sha256=InR8GCRiRW09zJk9Htx6YQE_--_KJhpEJCuCs_lJjKE,1936
+audio_engine/tts/__init__.py,sha256=85XrpIkxFrRvOn19mWphkeBjTaEcsrFECYK_ZoGv1dQ,987
+audio_engine/tts/base.py,sha256=vo0MSiep9QJQtpdCmDJWN-okK-ERYRA6Sk_g6IXCYZk,4475
+audio_engine/tts/cartesia.py,sha256=bxhkNbWpQmlPTZ8RWcVCQzG_Q2mYr3t1aAd9OonSSWQ,17011
+audio_engine/utils/__init__.py,sha256=WIeVykg3MqyOoCYEWsuzGyVniP8SIl9FE881ieR7WuE,250
+audio_engine/utils/audio.py,sha256=Z7avyNqhzZ2fnBxZ_d0qUglOCCvHSffBveg5CQWTCM0,5529
+atom_audio_engine-0.1.2.dist-info/METADATA,sha256=l8ztaq4vAmVNT4qg1mHhJW7R2sjTHs1BJsjTPpM108w,6690
+atom_audio_engine-0.1.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+atom_audio_engine-0.1.2.dist-info/top_level.txt,sha256=IyumwgFrsDL7nlZlBijX-0shiSVhhBCFPUNBRNKzWP4,13
+atom_audio_engine-0.1.2.dist-info/RECORD,,

atom_audio_engine-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+audio_engine

audio_engine/__init__.py

@@ -0,0 +1,80 @@
+"""
+Audio Engine - Pluggable audio-to-audio conversational AI framework.
+
+Orchestrates ASR → LLM → TTS pipeline with real-time streaming support.
+"""
+
+__version__ = "0.1.0"
+
+# Core exports
+from .core.pipeline import Pipeline
+from .core.config import (
+    AudioEngineConfig,
+    ASRConfig,
+    LLMConfig,
+    TTSConfig,
+    StreamingConfig,
+)
+from .core.types import (
+    AudioChunk,
+    TranscriptChunk,
+    ResponseChunk,
+    ConversationContext,
+)
+
+# ASR Providers
+from .asr.base import BaseASR
+from .asr.cartesia import CartesiaASR
+
+try:
+    from .asr.deepgram import DeepgramASR
+except ImportError:
+    pass
+
+# LLM Providers
+from .llm.base import BaseLLM
+from .llm.groq import GroqLLM
+
+# TTS Providers
+from .tts.base import BaseTTS
+from .tts.cartesia import CartesiaTTS
+
+# Streaming
+from .streaming.websocket_server import WebSocketServer
+
+# Integrations
+try:
+    from .integrations.geneface import GeneFacePipelineWrapper, GeneFaceConfig
+except ImportError:
+    pass
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core
+    "Pipeline",
+    "AudioEngineConfig",
+    "ASRConfig",
+    "LLMConfig",
+    "TTSConfig",
+    "StreamingConfig",
+    "AudioChunk",
+    "TranscriptChunk",
+    "ResponseChunk",
+    "ConversationContext",
+    # ASR
+    "BaseASR",
+    "CartesiaASR",
+    "DeepgramASR",
+    # LLM
+    "BaseLLM",
+    "GroqLLM",
+    # TTS
+    "BaseTTS",
+    "CartesiaTTS",
+    # Streaming
+    "WebSocketServer",
+    # Integrations
+    "GeneFacePipelineWrapper",
+    "GeneFaceConfig",
+]

audio_engine/examples/__init__.py

@@ -0,0 +1 @@
+"""Example scripts for the audio engine."""

audio_engine/examples/basic_stt_llm_tts.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""
+Example: Basic STT-LLM-TTS Pipeline
+
+Simple example showing how to use the core audio-to-audio pipeline:
+Audio Input → ASR → LLM → TTS → Audio Output
+
+Usage:
+    # Text input only (skips ASR)
+    python examples/basic_stt_llm_tts.py
+
+    # Audio file input (full STT-LLM-TTS)
+    python examples/basic_stt_llm_tts.py examples/audio_clip_1.mp3
+
+Setup:
+    export CARTESIA_API_KEY="your-cartesia-key"
+    export GROQ_API_KEY="your-groq-key"
+"""
+
+import asyncio
+import logging
+import sys
+import wave
+from pathlib import Path
+
+# Add parent to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from dotenv import load_dotenv
+from core.config import AudioEngineConfig
+from core.types import AudioChunk
+
+# Load environment variables from .env file
+load_dotenv(Path(__file__).parent.parent.parent / ".env")
+
+# Setup logging to see debug messages
+logging.basicConfig(
+    level=logging.DEBUG, format="%(name)s - %(levelname)s - %(message)s"
+)
+
+
+async def stream_audio_file(file_path: str, chunk_size: int = 4096):
+    """Stream audio from file (MP3, WAV, etc.) as chunks."""
+    try:
+        from pydub import AudioSegment
+    except ImportError:
+        print("❌ pydub required. Install: pip install pydub")
+        raise
+
+    file_path = Path(file_path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"Audio file not found: {file_path}")
+
+    print(f"📁 Loading: {file_path.name}")
+
+    # Load and convert to 16kHz mono 16-bit PCM
+    audio = AudioSegment.from_file(str(file_path))
+    audio = audio.set_channels(1).set_frame_rate(16000).set_sample_width(2)
+
+    duration_sec = len(audio) / 1000.0
+    print(f"✓ Audio: {duration_sec:.2f}s @ 16kHz mono\n")
+
+    # Stream as chunks
+    audio_bytes = audio.raw_data
+    chunk_index = 0
+    offset = 0
+    total_chunks = (len(audio_bytes) + chunk_size - 1) // chunk_size
+
+    while offset < len(audio_bytes):
+        chunk_data = audio_bytes[offset : offset + chunk_size]
+        chunk_index += 1
+        is_final = offset + chunk_size >= len(audio_bytes)
+
+        # Yield as AudioChunk object
+        yield AudioChunk(
+            data=chunk_data, sample_rate=16000, format="pcm_s16le", is_final=is_final
+        )
+        offset += chunk_size
+
+
+async def main():
+    """Run basic pipeline example."""
+    print("=" * 60)
+    print("Audio Engine: Basic STT-LLM-TTS Pipeline")
+    print("=" * 60)
+    print()
+
+    # Check if audio file provided as argument
+    audio_file = None
+    if len(sys.argv) > 1:
+        audio_file = sys.argv[1]
+
+    # Load configuration from environment
+    config = AudioEngineConfig.from_env()
+    print(f"✓ Config loaded:")
+    print(f"  - ASR: {config.asr.provider}")
+    print(f"  - LLM: {config.llm.provider}")
+    print(f"  - TTS: {config.tts.provider}")
+    print()
+
+    # Create pipeline from config
+    pipeline = config.create_pipeline(
+        system_prompt="You are a helpful assistant. Keep responses brief."
+    )
+    print(f"✓ Pipeline created")
+    print()
+
+    if audio_file:
+        # Full pipeline: Audio → ASR → LLM → TTS
+        print("-" * 60)
+        print("FULL PIPELINE: STT → LLM → TTS")
+        print("-" * 60 + "\n")
+
+        transcript = ""
+        llm_response = ""
+        audio_output = bytearray()
+        chunk_count = 0
+
+        try:
+            audio_generator = stream_audio_file(audio_file)
+
+            async for result in pipeline.stream(audio_generator):
+                if hasattr(result, "text"):
+                    class_name = result.__class__.__name__
+                    if class_name == "TranscriptChunk":
+                        transcript += result.text
+                        print(f"🎤 STT: {result.text!r}")
+                    elif class_name == "ResponseChunk":
+                        llm_response += result.text
+                        print(f"🧠 LLM: {result.text!r}")
+
+                elif hasattr(result, "data") and result.data:
+                    audio_output.extend(result.data)
+                    chunk_count += 1
+                    if chunk_count % 5 == 0:
+                        print(f"🔊 TTS: {len(audio_output)} bytes...")
+
+            if chunk_count > 0:
+                print(f"🔊 TTS: {len(audio_output)} bytes total")
+
+            # Save output
+            if audio_output:
+                output_dir = Path(__file__).parent / "output_samples"
+                output_dir.mkdir(exist_ok=True)
+                output_path = output_dir / "output_audio.wav"
+                with wave.open(str(output_path), "wb") as wav_file:
+                    wav_file.setnchannels(1)
+                    wav_file.setsampwidth(2)
+                    wav_file.setframerate(16000)
+                    wav_file.writeframes(bytes(audio_output))
+
+                duration_sec = len(audio_output) / 32000
+                print(f"\n✓ Audio saved to {output_path} ({duration_sec:.2f}s)")
+
+            # Print results
+            print("\n" + "=" * 60)
+            print("RESULTS")
+            print("=" * 60)
+            if transcript:
+                print(f"🎤 Transcribed: {transcript!r}")
+            if llm_response:
+                print(f"🧠 Response: {llm_response!r}")
+            print("=" * 60 + "\n")
+
+        except Exception as e:
+            print(f"❌ Error: {e}")
+            import traceback
+
+            traceback.print_exc()
+            return
+
+    else:
+        # Simplified pipeline: Text → LLM → TTS (no ASR)
+        print("-" * 60)
+        print("SIMPLIFIED PIPELINE: Text → LLM → TTS")
+        print("-" * 60 + "\n")
+
+        user_text = "What is the capital of France?"
+        print(f"User: {user_text}\n")
+
+        chunk_count = 0
+        total_bytes = 0
+        async for audio_chunk in pipeline.stream_text_input(user_text):
+            chunk_count += 1
+            total_bytes += len(audio_chunk.data)
+            print(f"  • Audio chunk {chunk_count}: {len(audio_chunk.data)} bytes")
+
+        print()
+        print("✓ Pipeline complete")
+        print(f"  Total audio: {total_bytes} bytes across {chunk_count} chunks")
+        print()
+        print("Conversation history:")
+        for msg in pipeline.context.messages:
+            role = msg.role.upper()
+            content = msg.content[:60]
+            print(f"  {role}: {content}...")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

audio_engine/examples/geneface_animation.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""
+Example: GeneFace++ Face Animation Integration
+
+Combines audio with GeneFace++ to generate an animated face
+that speaks the assistant's responses.
+
+GeneFaceIntegration takes a GeneFaceConfig (no pipeline parameter).
+It generates videos from audio bytes using:
+- generate_video(audio_bytes, sample_rate) -> video_path
+- generate_video_stream(audio_chunks) -> video_path
+
+Setup:
+    1. Clone GeneFace++ repository:
+       git clone https://github.com/yerfor/GeneFace-plusplus.git
+
+    2. Install GeneFace++ (see their docs)
+
+    3. Update geneface_path in this script
+
+Run:
+    python examples/geneface_animation.py
+"""
+
+import asyncio
+import sys
+import logging
+from pathlib import Path
+
+# Add parent to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from dotenv import load_dotenv
+from integrations.geneface import GeneFaceIntegration, GeneFaceConfig
+
+# Load environment variables from .env file
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+async def main():
+    """Run GeneFace++ animation example."""
+    print("=" * 60)
+    print("Audio Engine: GeneFace++ Face Animation")
+    print("=" * 60)
+    print()
+
+    # Setup GeneFace++ configuration
+    geneface_path = ""
+    if not geneface_path.exists():
+        logger.error(f"GeneFace++ path not found: {geneface_path}")
+        logger.info("Clone GeneFace-plusplus:")
+        logger.info("  git clone https://github.com/yerfor/GeneFace-plusplus.git")
+        logger.info()
+        logger.info("Update geneface_path variable in this script")
+        return
+
+    geneface_config = GeneFaceConfig(
+        geneface_path=str(geneface_path),
+        checkpoint_path=None,  # Specify trained model checkpoint if available
+        output_resolution=(512, 512),
+        fps=25,
+        device="cuda",  # or "cpu"
+    )
+
+    # Initialize GeneFace integration
+    try:
+        geneface = GeneFaceIntegration(config=geneface_config)
+        logger.info("GeneFace++ integration initialized")
+        print()
+
+        # Example: Generate video from audio
+        sample_rate = 16000
+        duration_seconds = 2
+        # For demo, create silence (all zeros)
+        audio_bytes = bytes(sample_rate * duration_seconds * 2)  # 16-bit PCM
+
+        logger.info(f"Generating video from {duration_seconds}s audio...")
+        video_path = await geneface.generate_video(
+            audio=audio_bytes,
+            sample_rate=sample_rate,
+            output_path=None,  # Uses temp file
+        )
+
+        logger.info(f"✓ Video saved to: {video_path}")
+        logger.info("GeneFace++ video generation working!")
+
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        logger.info("Make sure GeneFace++ is properly installed and configured")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

audio_engine/examples/personaplex_pipeline.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+Example: PersonaPlex Full-Duplex Pipeline
+
+PersonaPlex is a full-duplex audio pipeline allowing simultaneous
+input/output - user can interrupt while assistant is speaking.
+
+PersonaPlexPipeline API:
+- __init__(config=None, system_prompt="...", save_transcripts=True)
+- await start() -> connects to server
+- await stop() -> closes connection, saves transcript
+- async for (audio_chunk, text_chunk) in stream(audio_stream=None)
+- PersonaPlexConfig uses voice_prompt (not voice_id)
+
+Setup:
+    Obtain PersonaPlex server URL from RunPod or similar service
+    Set environment (optional, PersonaPlexConfig has defaults):
+       export PERSONAPLEX_SERVER="wss://your-server/"
+       export PERSONAPLEX_VOICE_PROMPT="NATF0.pt"
+
+Run:
+    python examples/personaplex_pipeline.py
+
+Note:
+    PersonaPlex is full-duplex (simultaneous I/O) unlike
+    sequential STT-LLM-TTS pipeline.
+"""
+
+import asyncio
+import sys
+import logging
+from pathlib import Path
+
+# Add parent to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from dotenv import load_dotenv
+from pipelines.personaplex import PersonaPlexPipeline, PersonaPlexConfig
+
+# Load environment variables from .env file
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+async def main():
+    """Run PersonaPlex full-duplex pipeline example."""
+    print("=" * 60)
+    print("Audio Engine: PersonaPlex Full-Duplex Pipeline")
+    print("=" * 60)
+    print()
+
+    # Configure PersonaPlex
+    config = PersonaPlexConfig(
+        # server_url="wss://your-personaplex-server",  # Uses default if not set
+        voice_prompt="NATF0.pt",  # Voice ID (not voice_id)
+        text_temperature=0.7,
+        audio_temperature=0.8,
+        save_transcripts=True,
+    )
+
+    logger.info("PersonaPlex Configuration:")
+    logger.info(f"  Server: {config.server_url[:50]}...")
+    logger.info(f"  Voice Prompt: {config.voice_prompt}")
+    logger.info(f"  Text Temp: {config.text_temperature}")
+    logger.info(f"  Audio Temp: {config.audio_temperature}")
+    print()
+
+    # Create pipeline
+    pipeline = PersonaPlexPipeline(
+        config=config,
+        system_prompt="You are a helpful, friendly AI assistant.",
+        save_transcripts=True,
+    )
+
+    try:
+        # Start connection
+        await pipeline.start()
+        logger.info("✓ Connected to PersonaPlex server")
+        logger.info("✓ Ready for full-duplex streaming")
+        print()
+
+        # Example: Stream bidirectional audio/text
+        logger.info("Streaming audio and text (press Ctrl+C to stop)...")
+        chunk_count = 0
+
+        async for audio_chunk, text_chunk in pipeline.stream():
+            if text_chunk:
+                logger.info(f"[Assistant] {text_chunk.text}")
+            if audio_chunk:
+                chunk_count += 1
+                logger.info(
+                    f"[Audio] Chunk {chunk_count}: {len(audio_chunk.data)} bytes"
+                )
+
+        # Stop and save transcript
+        transcript_data = await pipeline.stop()
+        logger.info("✓ Pipeline stopped")
+        if transcript_data:
+            logger.info(f"✓ Transcript saved (session: {transcript_data.session_id})")
+
+    except KeyboardInterrupt:
+        logger.info("\n⏹️  Stopped by user")
+        await pipeline.stop()
+    except Exception as e:
+        logger.error(f"Error: {e}")
+        logger.info("Make sure PersonaPlex server is running and accessible")
+        await pipeline.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

audio_engine/examples/websocket_server.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+Example: WebSocket Server for Real-Time Audio Streaming
+
+Runs a WebSocket server that accepts live audio streams and returns
+responses in real-time. Clients can send binary audio and receive text
+transcripts + response audio.
+
+Setup:
+    export DEEPGRAM_API_KEY="your-deepgram-key"
+    export GROQ_API_KEY="your-groq-key"
+    export CARTESIA_API_KEY="your-cartesia-key"
+
+Run:
+    python examples/websocket_server.py
+
+Then connect a WebSocket client to ws://localhost:8765
+
+Example client (JavaScript):
+    const ws = new WebSocket("ws://localhost:8765");
+    ws.binaryType = "arraybuffer";
+    ws.onopen = () => {
+        // Send audio data
+        ws.send(audioBuffer);
+        // Signal end of speech
+        ws.send(JSON.stringify({"type": "end_of_speech"}));
+    };
+    ws.onmessage = (event) => {
+        if (typeof event.data === "string") {
+            console.log("Event:", JSON.parse(event.data));
+        } else {
+            console.log("Audio data:", event.data);
+        }
+    };
+"""
+
+import asyncio
+import sys
+import logging
+from pathlib import Path
+
+# Add parent to path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from dotenv import load_dotenv
+from core.config import AudioEngineConfig
+from streaming.websocket_server import run_server_from_config
+
+# Load environment variables from .env file
+load_dotenv(Path(__file__).parent.parent / ".env")
+
+# Setup logging
+logging.basicConfig(
+    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+async def main():
+    """Run WebSocket server."""
+    print("=" * 60)
+    print("Audio Engine: WebSocket Server")
+    print("=" * 60)
+    print()
+
+    # Load configuration from environment
+    config = AudioEngineConfig.from_env()
+    logger.info(f"Config loaded")
+    logger.info(f"  ASR: {config.asr.provider}")
+    logger.info(f"  LLM: {config.llm.provider}")
+    logger.info(f"  TTS: {config.tts.provider}")
+    logger.info(f"  Host: {config.streaming.host}")
+    logger.info(f"  Port: {config.streaming.port}")
+    print()
+
+    try:
+        await run_server_from_config(
+            config,
+            system_prompt="You are a helpful audio assistant. Keep responses brief and natural.",
+        )
+    except KeyboardInterrupt:
+        logger.info("Server shutting down...")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())