Ziggy, a 24/7 voice assistant on Muse Spark

# Ziggy 🎙️ — 24/7 Voice Assistant

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
![Status](https://img.shields.io/badge/status-active_development-green.svg)

A hands-free, always-on voice companion that runs on your laptop.
Say the wake word, talk naturally, get spoken responses — with conversation
memory, so it remembers what you told it yesterday.

**Design principle:** silence is free. Wake-word detection runs locally, and
API tokens are consumed only while you're actively talking.

## ✨ Features

- **Wake-word activation** — Porcupine-powered on-device "ziggy" detection (push-to-talk fallback included)
- **Speech-to-text** — local Whisper (tiny), auto-detects Hindi & English, works offline
- **Conversational brain** — powered by Muse Spark via the Meta Model API
- **Text-to-speech** — offline voice output, no API key needed
- **Conversation memory** — every exchange is logged locally; the assistant recalls past context
- **Privacy-first** — your API key and memory never leave your machine (`.env` and `memory.jsonl` are git-ignored)

## 🏗️ Architecture

```
 🎤 microphone (24/7, local)
      │
      ▼
 ┌───────────┐   wake word detected   ┌──────────┐
 │  wake.py  │ ─────────────────────▶ │ ears.py  │  audio → text (faster-whisper)
 └───────────┘                        └──────────┘
                                            │ text
                                            ▼
                                      ┌──────────┐
                                      │ brain.py │  Muse Spark (Meta Model API)
                                      └──────────┘
                                            │ text
                                            ▼
 ┌──────────┐                         ┌──────────┐
 │ memory.py│ ◀── every turn logged ── │ mouth.py │  text → speech (pyttsx3)
 └──────────┘                         └──────────┘
```

| Component | Role | Cost |
|---|---|---|
| `wake.py` | Wake-word detection (Porcupine, or push-to-talk) | Free |
| `ears.py` | Speech → text (Whisper tiny, CPU) | Free, offline |
| `brain.py` | Reasoning & replies (Muse Spark) | ~10–15k tokens / hour of active chat |
| `mouth.py` | Text → speech | Free, offline |
| `memory.py` | JSONL conversation log + recall | Free |

## 🚀 Quick Start