Compound Voice: A real-time AI voice assistant powered by Groq's Compound with internet search capabilities.

Overview • Installation • Usage • Development • Deployment

compound-voice-demo-trimmed.mp4

Overview

Compound Voice is a realtime AI voice assistant that combines the power of Groq's Compound with internet search capabilities.

Key Features:

• 🎯 Real-time Voice Interaction - Natural conversation flow with minimal latency
• 🔍 Internet Search Integration - Compound automatically searches for current information when needed
• ⚡ Powered by Groq - Lightning-fast and performant inference with Groq
• 🎙️ Advanced Audio Processing - Voice activity detection and noise filtering
• 📱 Responsive Design - Works across desktop and mobile devices
• 🔧 Customizable Voices - Multiple ElevenLabs voice options (or any TTS supported by LiveKit)

This project consists of two main components:

• Agent (Python): Handles voice agent session, AI inference, and tool execution
• Frontend (Next.js): Provides the web interface for communication with the voice agent

Installation

Prerequisites

• Python 3.11+
• Node.js 18+ with pnpm
• API keys: Groq, LiveKit, ElevenLabs (or other TTS provider)

For Development (Recommended)

1. Clone the repository:

git clone https://github.com/build-with-groq/compound-voice.git
cd compound-voice

2. Set up the agent backend:

cd agent
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Configure agent environment:

Create agent/.env from the example:

cp .env.example .env
# Edit .env with your API keys

4. Set up the frontend (in a separate terminal window):

cd frontend  # or `cd ../frontend` from the same terminal window
pnpm install

5. Configure frontend environment:

Create frontend/.env.local:

cp .env.example .env.local
# Edit .env.local with your API keys

Hosted Version

We have provided support for you to deploy and self-host Compound Voice (and apps you may create utilizing it). However, Groq does not currently host Compound Voice.

Usage

Running Locally

1. Start the agent:

cd agent
python main.py dev

2. Start the frontend (in a separate terminal window):

cd frontend
pnpm dev

3. Open http://localhost:3000 in your browser

How It Works

1. Click "Start Conversation" to begin
2. Speak naturally - the agent detects when you start and stop talking
3. Get intelligent responses - Compound automatically searches for current information when needed
4. View search results - See sources and relevance scores for search-based responses

Development

Project Structure

compound-voice/
├── agent/                     
│   ├── main.py                # Main agent orchestrator
│   ├── health_server.py       # Health check for cloud deployment
│   ├── system_prompt.txt      # Agent personality and instructions
│   ├── Dockerfile             # Agent containerization      
│   └── requirements.txt
└── frontend/                  
    ├── src/
    │   ├── components/
    │   │   ├── audio/         # Audio visualizers and microphone components
    │   │   ├── conversation/  # Main conversation interface and playground
    │   │   └── ui/            # UI components and utilities
    │   ├── hooks/             # React hooks for state management
    │   ├── lib/               # Utilities and types
    │   └── pages/             # Next.js pages and API routes
    ├── public/                # Static assets
    └── Dockerfile             # Frontend containerization           

Key Components

Agent (agent/main.py)

• CustomGroqLLM: Integrates with Groq's Compound for tool execution
• Voice Processing: Handles STT (Speech-to-Text) and TTS (Text-to-Speech)
• Search Integration: Extracts and forwards search results to frontend
• Real-time Communication: Uses LiveKit for bidirectional data streaming

Frontend Components

• Conversation Components: Main conversation interface (Playground), room management (RoomComponent), and search results display (ToolResultsDisplay)
• Audio Components: Real-time audio visualizers, microphone controls, and device selection
• UI Components: Reusable interface elements and utilities

Customization

Modifying Agent Behavior

Edit agent/system_prompt.txt to change:

• Response style and personality
• Search triggers and formatting
• Conversation flow patterns

Deployment

Simply deploy the frontend to your hosting provider of your choice.

To deploy the LiveKit agent, please see LiveKit's documentation for support. Also see examples of self-hosting and LiveKit Cloud deployments.

The following guide outlines how to deploy a LiveKit agent and frontend using Google Cloud Run.

Google Cloud Run

1 Create the services on Cloud Run

2. Build and push agent container:

docker build -t us-west1-docker.pkg.dev/<YOUR_GCP_ID>/<LOCATION>:latest -f agent/Dockerfile --platform linux/amd64 ./agent

docker push us-west1-docker.pkg.dev/<YOUR_GCP_ID>/<LOCATION>:latest

3. Build and push frontend container:

docker build --build-arg NEXT_PUBLIC_LIVEKIT_URL=wss://groqlabs-test-4uciy1ac.livekit.cloud	 -t us-west1-docker.pkg.dev/<YOUR_GCP_ID>/<LOCATION>:latest -f frontendDockerfile --platform linux/amd64 ./frontend

docker push us-west1-docker.pkg.dev/<YOUR_GCP_ID>/<LOCATION>:latest

4. Deploy to Cloud Run with appropriate environment variables and scaling settings.

Environment Variables for Production

Agent:

• GROQ_API_KEY: Groq API key
• LIVEKIT_URL: LiveKit server URL
• LIVEKIT_API_KEY / LIVEKIT_API_SECRET: LiveKit credentials
• ELEVEN_API_KEY: ElevenLabs API key

Frontend:

• LIVEKIT_API_KEY / LIVEKIT_API_SECRET: LiveKit credentials
• NEXT_PUBLIC_LIVEKIT_URL: Public LiveKit WebSocket URL

License

Compound Voice is covered under an MIT license. The ElevenLabs API is not covered by the MIT license and remain subject to ElevenLabs' own Terms of Service.

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository and create a feature branch
2. Set up the development environment following the installation guide
3. Make your changes and test thoroughly
4. Submit a pull request with a clear description

For issues and feature requests, please open an issue on GitHub.

Share what you create with Groq on socials!