voice-assistant-example

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

voice-assistant-example

★ 10 Open GitHub ↗

Example setup for a local Voice Assistant.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Voice Assistant Example

Minimal reproducible example for building a voice assistant with Home Assistant, local STT/TTS, and Groq for the conversation agent.

## What's Included

- **Home Assistant** - Core automation platform
- **Whisper** - Local speech-to-text (Wyoming protocol)
- **Piper** - Local text-to-speech (Wyoming protocol)
- **SearXNG** - Self-hosted metasearch engine
- **HTTP Service** - Simple API for tool calls (search example)

## Prerequisites

- Docker & Docker Compose
- [Home Assistant Voice PE](https://www.home-assistant.io/voice-pe/) ($60) or any ESPHome voice satellite
- [Groq API key](https://console.groq.com) (free tier works fine)

## Quick Start

1. **Clone and configure:**
   ```bash
   cp .env.example .env
   # Edit .env and add your GROQ_API_KEY
   ```

2. **Start the stack:**
   ```bash
   docker-compose up -d
   ```

3. **Configure Home Assistant** (http://localhost:8123):

a. Add Wyoming integrations:
      - Settings → Devices & Services → Add Integration
      - Add **Whisper**: host = your server IP, port = 10300
      - Add **Piper**: host = your server IP, port = 10200

b. Install Extended OpenAI Conversation:
      - Install [HACS](https://hacs.xyz/) if needed
      - HACS → Integrations → Custom repositories
      - Add: `https://github.com/jekalmin/extended_openai_conversation`
      - Install and restart Home Assistant

c. Configure Extended OpenAI Conversation:
      - Settings → Devices & Services → Add Integration → Extended OpenAI Conversation
      - API Key: your Groq API key
      - Base URL: `https://api.groq.com/openai/v1`
      - Model: `llama-3.1-8b-instant`
      - Click Configure and paste the contents of `tool-configs/search-tools.yml`
      - Replace `YOUR_SERVER_IP` with your actual server IP

d. Create Voice Assistant:
      - Settings → Voice assistants → Add Assistant
      - Conversation agent: Extended OpenAI Conversation
      - Speech-to-text: Whisper
      - Text-to-speech: Piper

e. Add Voice PE:
      - Power on your Voice PE
      - It should auto-discover via ESPHome
      - Configure it to use your new voice assistant pipeline

## Testing

Test the search endpoint directly:
```bash
curl -X POST http://localhost:8765/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what is the weather in New York"}'
```

## Groq Free Tier Limits

- 30 requests/minute
- 14,400 requests/day
- 500K tokens/day

More than enough for personal voice assistant use.

## Project Structure

```
.
├── docker-compose.yml      # All services
├── http-service/           # Example tool API
│   ├── src/server.ts       # Search endpoint
│   └── Dockerfile
├── tool-configs/           # HA tool definitions
│   └── search-tools.yml
└── data/                   # Persistent data (gitignored)
```

## Adding More Tools

1. Add an endpoint to `http-service/src/server.ts`
2. Create a tool definition in `tool-configs/`
3. Add the tool to Extended OpenAI Conversation in Home Assistant

See the [full example repository](https://github.com/your-repo/voice-assistant) for more tools (timers, weather, shopping lists, Spotify).

## Resources

- [Extended OpenAI Conversation](https://github.com/jekalmin/extended_openai_conversation)
- [Wyoming Protocol](https://github.com/rhasspy/wyoming)
- [Home Assistant Voice](https://www.home-assistant.io/voice_control/)
- [Groq API](https://console.groq.com/docs)
- [SearXNG](https://docs.searxng.org/)

voice-assistant-example

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README