Metadata-Version: 2.4
Name: edgevoiceai
Version: 0.1.3
Summary: A modular, full-duplex conversational Voice AI framework for edge devices (Raspberry Pi) and laptops (macOS, Linux, Windows).
Author-email: Hasmukh Mer <mhgn0001@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/merhasmukh/edgevoiceai
Project-URL: Documentation, https://merhasmukh.github.io/edgevoiceai
Project-URL: Repository, https://github.com/merhasmukh/edgevoiceai.git
Project-URL: Issues, https://github.com/merhasmukh/edgevoiceai/issues
Keywords: voice-ai,realtime,full-duplex,gemini-live,raspberry-pi,barge-in,rag,edge-computing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=12.0
Requires-Dist: pyaudio>=0.2.14
Requires-Dist: httpx>=0.27.0
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.11.0; extra == "qdrant"
Provides-Extra: pinecone
Requires-Dist: pinecone>=5.0.0; extra == "pinecone"
Provides-Extra: media
Requires-Dist: pygame>=2.5.0; extra == "media"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.28.0; extra == "docs"
Provides-Extra: all
Requires-Dist: qdrant-client>=1.11.0; extra == "all"
Requires-Dist: pinecone>=5.0.0; extra == "all"
Requires-Dist: pygame>=2.5.0; extra == "all"
Requires-Dist: mkdocs-material>=9.5.0; extra == "all"
Requires-Dist: mkdocstrings[python]>=0.28.0; extra == "all"
Dynamic: license-file

# EdgeVoiceAI

<p align="center">
  <strong>A modular, full-duplex conversational voice AI framework for Python 3.10+</strong><br>
  <em>Built for edge devices (Raspberry Pi, Linux) and laptops (macOS, Windows) powered by Google Gemini Live.</em>
</p>

<p align="center">
  <a href="https://pypi.org/project/edgevoiceai/"><img src="https://img.shields.io/pypi/v/edgevoiceai.svg" alt="PyPI version"></a>
  <a href="https://pypi.org/project/edgevoiceai/"><img src="https://img.shields.io/pypi/pyversions/edgevoiceai.svg" alt="Python Versions"></a>
  <a href="https://github.com/merhasmukh/edgevoiceai/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://merhasmukh.github.io/edgevoiceai/"><img src="https://img.shields.io/badge/docs-MkDocs-teal.svg" alt="Documentation"></a>
</p>

---

## 🌟 Overview

**EdgeVoiceAI** is a developer-first Python library designed to build low-latency, full-duplex conversational voice assistants from scratch. It connects physical hardware microphones and speakers directly with Google Gemini's real-time bidirectional streaming API (`bidiGenerateContent`), enabling natural spoken interactions with instant turn-taking and conversational barge-in interruptions.

Unlike traditional voice wrappers that chain disjointed Speech-To-Text (STT) $\rightarrow$ LLM $\rightarrow$ Text-To-Speech (TTS) pipelines with noticeable latency, EdgeVoiceAI operates over a single, continuous, bidirectional audio WebSocket connection.

---

## 🏗️ Architecture

<p align="center">
  <img src="https://raw.githubusercontent.com/merhasmukh/edgevoiceai/main/docs/assets/architecture.svg" alt="EdgeVoiceAI Architecture" width="100%">
</p>

```text
+-----------------------------------------------------------------------+
|        Client Device (macOS / Linux / Windows / Raspberry Pi)         |
|                                                                       |
|   [🎙️ MicrophoneStream (16kHz Native Mono PCM)]                       |
|                │                                                      |
|                ▼                                                      |
|   [⚡ VoiceActivityDetector (Energy Gating & Syllable Onset)]          |
|                │                                                      |
|                ▼                                                      |
|   [📤 WebSockets Client (realtimeInput audio frames)]                 |
|                │                                      ▲               |
+────────────────┼──────────────────────────────────────┼───────────────+
                 │                                      │
                 │ 16kHz PCM Stream                     │
                 ▼                                      │
+───────────────────────────────────────────────────────┼───────────────+
|                  Google Gemini Live Service           │               |
|                 (gemini-2.0-flash-exp / live)         │               |
+───────────────────────────────────────────────────────┼───────────────+
                 │                                      │
                 │ 24kHz Streaming Audio & Tool Calls   │
                 ▼                                      │
+────────────────┼──────────────────────────────────────┼───────────────+
|                ▼                                                      |
|   [📥 WebSockets Receiver (serverContent)]                            |
|          │                                                            |
|          ├─────────────────────────────┐                              |
|          ▼                             ▼                              |
|   [🔊 AudioPlayer (24kHz PCM)]   [🔧 Tool Dispatcher (ToolRegistry)]  |
|    • <50ms Instant Barge-In Cancel             │                      |
|    • Acoustic Echo Suppression                 ▼                      |
|                                  [🧠 Memory & Vector Stores]          |
|                                     (SQLite / Qdrant / Pinecone)      |
+-----------------------------------------------------------------------+
```

---

## ✨ Key Features

- **⚡ Ultra-Low Latency & Instant Barge-In**: Real-time 16kHz continuous streaming. When you speak while the assistant responds, playback clears instantly (<50ms) to yield the floor naturally.
- **🧩 Self-Describing Tools with Prompt Composition**: Each tool declares its own JSON schema, execution callback, and prompt etiquette instructions (`prompt_instruction`). The framework automatically synthesizes these instructions into the agent's system prompt.
- **🎙️ Cross-Platform Audio Engine**: Powered by PortAudio with automatic hardware enumeration across macOS (CoreAudio), Linux / Raspberry Pi (ALSA/PulseAudio), and Windows (WASAPI/MME).
- **🔍 Plug-and-Play RAG Integration**: Built-in `RAGRetriever` with chunking and native vector store backends for `InMemoryVectorStore`, `QdrantVectorStore`, and `PineconeVectorStore`.
- **🛡️ Conversational Guardrails**: Turn-aware farewell detectors, topic safety guards, and entity memory management.
- **📲 Built-in Notification Tools**: Two-turn confirmation WhatsApp dispatch tool with phone number normalization.

---

## 📦 Installation

### 1. Install System Audio Dependencies (PortAudio)

EdgeVoiceAI uses PortAudio for native, cross-platform audio streaming.

- **macOS**:
  ```bash
  brew install portaudio
  ```
- **Linux / Raspberry Pi**:
  ```bash
  sudo apt-get update
  sudo apt-get install -y portaudio19-dev libasound2-dev python3-pyaudio
  ```
- **Windows**:
  - **Recommended Python**: **`3.10`, `3.11`, or `3.12`**. Official pre-compiled binary wheels for `pyaudio` are provided automatically—no compilers required.
  - **Notice for Python 3.14+**: Python 3.14 does not have pre-built wheels on PyPI yet. If you see `Microsoft Visual C++ 14.0 or greater is required`, either:
    1. *(Recommended)* Create your virtual environment with Python 3.11 or 3.12: `py -3.11 -m venv venv`
    2. Or install [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) (select *"Desktop development with C++"*).

### 2. Install EdgeVoiceAI via pip

```bash
# Core package
pip install edgevoiceai

# With specific optional extras
pip install "edgevoiceai[qdrant]"    # Qdrant vector store support
pip install "edgevoiceai[pinecone]"  # Pinecone vector store support
pip install "edgevoiceai[media]"     # Pygame audio sound effects

# Or install all extras
pip install "edgevoiceai[all]"
```

---

## 🚀 5-Minute Quickstart

### 1. Set Your Gemini API Key

```bash
export GEMINI_API_KEY="your-google-ai-studio-api-key"
```

### 2. Run a Full-Duplex Voice Assistant

```python
import asyncio
import os
from dotenv import load_dotenv
from edgevoiceai import (
    BaseTool,
    InMemoryMemoryStore,
    ToolExecutionContext,
    ToolRegistry,
    ToolResult,
    VoiceAgent,
    VoiceConfig,
)

# Load GEMINI_API_KEY from .env
load_dotenv()


# Define a custom tool with prompt instructions
class BookAppointmentTool(BaseTool):
    @property
    def name(self) -> str:
        return "book_appointment"

    @property
    def description(self) -> str:
        return "Schedules a consultation appointment for the user."

    @property
    def parameters_schema(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "Customer name"},
                "date": {"type": "string", "description": "Date of appointment (YYYY-MM-DD)"},
                "time": {"type": "string", "description": "Time (e.g. 10:00 AM)"},
            },
            "required": ["name", "date", "time"],
        }

    @property
    def prompt_instruction(self) -> str:
        return (
            "When scheduling, ask for the customer's name, desired date, and preferred time. "
            "Always verbally confirm all details before executing book_appointment."
        )

    async def execute(self, params: dict, context: ToolExecutionContext) -> ToolResult:
        name = params.get("name")
        date = params.get("date")
        time = params.get("time")
        # In a real app, write to database or calendar API
        return ToolResult(
            status="success",
            message=f"Appointment booked for {name} on {date} at {time}.",
            data={"status": "confirmed", "booking_id": "APT-1001"},
        )


async def main():
    api_key = os.environ.get("GEMINI_API_KEY")
    if not api_key:
        raise ValueError("Please set the GEMINI_API_KEY environment variable.")

    # Configure the voice session
    config = VoiceConfig(
        api_key=api_key,
        voice="Puck",  # Puck, Charon, Aoede, Fenrir, Kore
        system_instruction=(
            "You are a friendly, concise voice assistant. "
            "Keep responses natural, conversational, and direct."
        ),
    )

    # Register tools and memory
    registry = ToolRegistry()
    registry.register(BookAppointmentTool())
    memory = InMemoryMemoryStore()

    agent = VoiceAgent(config=config, tools=registry, memory=memory)

    print("🎙️ Starting Voice Assistant... Speak into your microphone!")
    try:
        await agent.run_edge()
    except KeyboardInterrupt:
        print("\nStopping...")
    finally:
        agent.stop()


if __name__ == "__main__":
    asyncio.run(main())
```

---

## 📖 Documentation

Comprehensive documentation, tutorials, architecture deep-dives, and API references are available at:
**[https://merhasmukh.github.io/edgevoiceai/](https://merhasmukh.github.io/edgevoiceai/)**

---

## 📄 License

This project is licensed under the [MIT License](LICENSE).
