# 🎙️ Alexandr Smart Speaker

<div align="center">

![Python](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white&style=for-the-badge)
![Platform](https://img.shields.io/badge/Platform-Linux-FCC624?logo=linux&logoColor=black&style=for-the-badge)
![License](https://img.shields.io/badge/License-MIT-45a163?style=for-the-badge)

**Alexandr** is a personal voice assistant for Linux that leverages modern AI technologies to create natural conversations. It listens, understands context, translates languages, checks the weather, and manages your time.

[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Architecture](#-architecture)

</div>

---

## ✨ Features

### 🧠 Artificial Intelligence
*   **Smart Dialogue**: Context-aware conversations powered by **Perplexity AI** (Llama 3.1).
*   **Translator**: Instant bidirectional translation (RU ↔ EN) with native pronunciation.

### 🗣️ Voice Interface
*   **Wake Word**: Activates on the phrase **"Alexandr"** (powered by Porcupine).
*   **Speech Recognition**: Fast and accurate Speech-to-Text via **Deepgram**.
*   **Text-to-Speech**: Natural sounding offline voice synthesis using **Silero TTS**.

### 🛠️ Tools
*   **⛅ Weather**: Detailed forecasts (current, daily range, hourly) via Open-Meteo.
*   **⏰ Alarm & Timer**: Voice-controlled alarms and timers.
*   **🔊 System Control**: Adjust system volume via voice commands.

---

## ⚙️ Installation

### 1. Prerequisites
*   **OS**: Linux
*   **Python**: 3.9+
*   **System Libraries**:
    ```bash
    sudo apt-get install portaudio19-dev libasound2-dev mpg123
    ```

### 2. Setup
```bash
# Clone the repository
git clone https://github.com/your-username/alexander_smart-speaker.git
cd alexander_smart-speaker

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

### 3. Configuration
Create a `.env` file based on the example:
```bash
cp .env.example .env
```

Fill in your API keys in `.env`:
```ini
# AI & Speech APIs
PERPLEXITY_API_KEY=pplx-...
DEEPGRAM_API_KEY=...
PORCUPINE_ACCESS_KEY=...

# TTS Settings
TTS_EN_SPEAKER=en_0
TTS_RU_SPEAKER=eugene

# Weather Location (Your City Coordinates)
WEATHER_LAT=63.56
WEATHER_LON=53.69
WEATHER_CITY=Ukhta
```

---

## 🚀 Usage

Start the assistant:
```bash
python run.py
```

### Command Examples

| Category | User Command (RU) | Action |
|----------|-------------------|--------|
| **Activation** | "Alexandr" | Assistant starts listening |
| **Dialogue** | "Почему небо голубое?" | Ask AI with context retention |
| **Weather** | "Какая сейчас погода?", "Нужен ли зонт?" | Get weather forecast |
| **Translation** | "Переведи на английский: привет, как дела?" | Translate and speak in EN |
| **Alarm** | "Разбуди меня в 7:30", "Поставь таймер на 5 минут" | Set alarm or timer |
| **Volume** | "Громкость 5", "Громкость 8" | Set system volume level |
| **Control** | "Стоп", "Хватит", "Повтори" | Stop speech or repeat last phrase |

---

## 🏗️ Architecture

```mermaid
graph TD
    Mic[🎤 Microphone] --> Wake[Wake Word<br>(Porcupine)]
    Wake -->|Activated| STT[STT<br>(Deepgram)]
    
    STT --> Router{Command Router}
    
    Router -->|Forecast| Weather[⛅ Weather<br>(Open-Meteo)]
    Router -->|Time| Alarm[⏰ Alarm/Timer]
    Router -->|Settings| Vol[🔊 Volume]
    Router -->|Translate| Translator[A↔B Translator]
    Router -->|Query| AI[🧠 Perplexity AI]
    
    Weather --> TTS
    Alarm --> TTS
    Vol --> TTS
    Translator --> TTS
    AI --> Cleaner[Text Cleaner]
    Cleaner --> TTS[🗣️ TTS<br>(Silero)]
    
    TTS --> Speaker[🔊 Speaker]
```

## 📂 Project Structure
*   `app/main.py` — Entry point, main event loop.
*   `app/audio/` — Audio processing modules (STT, TTS, Wake Word).
*   `app/core/` — AI logic, configuration, text cleaning.
*   `app/features/` — Skills (Weather, Alarm, Timer).
*   `assets/` — Models (Porcupine) and sound effects.
*   `data/` — Persistent state (alarms).

---

## 🛠️ Troubleshooting
*   **Deepgram Error 400**: Check your API key balance and validity in `.env`.
*   **No Sound**: Ensure `amixer` is installed and the default audio output is correctly configured in your OS.
*   **Alarm not playing**: Verify that `mpg123` is installed (`sudo apt install mpg123`).

## 📄 License
MIT License. See `LICENSE.txt` for details.