Metadata-Version: 2.4
Name: vaani-assistant
Version: 1.0.0
Summary: Enterprise-grade, low-latency Gemini Live voice assistant for Linux desktop.
Author-email: Yash Thakare <thakareyash74@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/yashthakare93/vaani
Project-URL: Repository, https://github.com/yashthakare93/vaani
Project-URL: Issues, https://github.com/yashthakare93/vaani/issues
Keywords: voice-assistant,gemini,ai,linux,tts,stt,gtk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: Console
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: sounddevice>=0.4.6
Requires-Dist: soundfile>=0.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: edge-tts>=6.1.0
Requires-Dist: google-genai>=2.3.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# Vaani (वाणी) 🎙️✨

**Real-time bidirectional AI voice assistant built on the Google Gemini Live API with a transparent glassmorphic GTK4 desktop HUD.**

<p align="center">
<pre>
   _  _   _____   _____   _   _   _ 
  | | | | /  _  \ /  _  \ | \ | | | |
  | | | | | |_| | | |_| | |  \| | | |
  | | | | |  _  | |  _  | | . ` | | |
  \ \_/ / | | | | | | | | | |\  | | |
   \___/  \_| |_/ \_| |_/ \_| \_/ \_/

</pre>
</p>

<p align="center">
  <code>◌ Standby</code> ➔ <code>  ▂▅▇ Listening</code> ➔ <code>◈ Thinking</code> ➔ <code>▇▅▃  Speaking</code>
</p>

---

## Overview

Vaani is a desktop voice assistant that speaks and listens using a low-latency, bidirectional audio stream connected directly to Google's Gemini Live model over WebSockets. Designed specifically for Linux desktop environments (optimized for GNOME on Ubuntu/Debian), it completely bypasses traditional wake-word latency and intermediate speech-to-text transcription. Audio flows in and out of Gemini natively, providing a natural, sub-second response loop.

A glassmorphic top-center Head-Up Display (HUD) overlay reflects assistant states using real-time Cairo waveform visualization, state-aware accent colors, and status indicators.

---

## Core Capabilities

- **Bidirectional Audio Stream**: Constant 16 kHz microphone input stream and 24 kHz speaker output stream via persistent WebSockets.
- **Glassmorphic HUD Overlay**: Transparent panel pinned to the top-center of the monitor displaying real-time engine states with a 30 FPS hardware-accelerated visualizer.
- **Native Tool Calling**: Executes desktop automation tools (launch GNOME Terminal, open websites, capture compositor-aware screenshots, manage notes, access memory) silently in the background.
- **Bilingual Personality**: Standardized on a friendly, conversational feminine voice with custom Hinglish grammar safeguards.
- **Mute-First Privacy**: Instant manual and system-level mute transitions with an optimized interruption pipeline.
- **Interactive Onboarding Wizard**: A self-guided CLI setup that safely stores your configurations in user-space directory.

---

## Installation

### The Recommended Install (Native Debian Package)

You can download and install the official native Debian package system-wide in one go (resolves PipeWire and system GObject dependencies automatically):

```bash
curl -LO https://github.com/yashthakare93/vaani/releases/download/v1.0.0/vaani_1.0.0_amd64.deb && sudo apt install ./vaani_1.0.0_amd64.deb
```

Once installed, simply run the onboarding setup wizard once to configure your Gemini API key:
```bash
vaani --setup
```

And launch the assistant:
```bash
vaani
```

---

### Developer Installation (Run from Source)

Ideal for development, customizing tools, or modifying the GTK4 overlay interface.

#### 1. Install System Dependencies (Ubuntu 24.04 / Linux Mint)
```bash
sudo apt-get update
sudo apt-get install -y \
  python3 python3-pip python3-venv python3-gi python3-gi-cairo \
  gir1.2-gtk-4.0 libportaudio2 portaudio19-dev libsndfile1 ffmpeg \
  pipewire pipewire-pulse pulseaudio-utils xdg-utils
```

#### 2. Clone the Repository
```bash
git clone https://github.com/yashthakare93/vaani.git
cd vaani
```

#### 3. Set Up Python Virtual Environment
```bash
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -e .
```

#### 4. Run the Setup & Onboarding
```bash
# Set your Gemini API key and profile details
python3 -m vaani_assistant --setup
```

#### 5. Launch the Assistant
```bash
python3 -m vaani_assistant
```

---

## Command Line Interface (CLI) Reference

Once installed, the `vaani` command is available system-wide:

```bash
vaani              # Launches the voice assistant and GTK HUD
vaani --setup      # Launches the interactive onboarding setup wizard
vaani --version    # Prints the installed package version
vaani --help       # Displays available options and flags
```

---

## Real-Time HUD States

The transparent overlay dynamically changes colors and symbols to represent Vaani's cognitive state:

| State | Accent Color | Visualizer Behavior | Symbol | Description |
| :--- | :--- | :--- | :---: | :--- |
| **Standby** | Grey | Static flat line | `◌` | Waiting for user conversation to begin |
| **Listening** | Accent Blue | Active real-time microphone RMS waves | *(waves)* | Audio stream actively processing your voice |
| **Thinking** | Purple Accent | Subtle pulsing diamond | `◈` | Gemini processing query / running tool calls |
| **Speaking** | Green Accent | Active real-time assistant speaker waves | *(waves)* | Native audio playback active |
| **Muted** | Crimson Red | Static flat line | `⊘` | Microphone input disabled (Privacy Mode) |
| **Offline** | Grey / Red | Static flat line | `✕` | Network disconnected / connection retry loop |

---

## systemd User Service (Autostart)

If you installed via the `.deb` package (Option A), you can configure Vaani to start automatically when you log into your desktop environment:

```bash
# Enable the user service
systemctl --user enable vaani

# Start the service immediately
systemctl --user start vaani

# Stop the service
systemctl --user stop vaani

# View real-time logs
journalctl --user -u vaani -f
```

---

## Developer Diagnostics

Before modifying code or reporting issues, use the diagnostics utility to verify your current environment state:

```bash
python3 scripts/diagnostics.py
```

This utility performs tests on the following subsystems:
- **API Key Validity**: Tests connection to Google Gemini developer endpoints.
- **Audio Pipeline**: Validates sounddevice sample rate and system output.
- **Socket Connectivity**: Verifies PulseAudio/PipeWire sockets.
- **GTK Libraries**: Verifies GObject introspections and CSS rendering.
- **Data Integrity**: Checks JSON databases in `data/`.

---

## Directory Mappings

- **Global Config File**: `~/.config/vaani/.env` (Stores your secure `GEMINI_API_KEY`)
- **Venv Workspace**: `~/.local/share/vaani/venv/`
- **Application Databases**: `~/.local/share/vaani/data/` (Contains user facts, notes, memory maps)
- **Shared Docs**: `/usr/share/doc/vaani/`

---

## License & Support

Standard MIT License. Created by **Yash Thakare**, 2026.
For any issues, please run system diagnostics first and reference the results in your inquiry.
