duotalk 1.0.5

Advanced multi-agent voice conversation system with customizable personas and modes

DuoTalk 🎭

Advanced Multi-Agent Voice Conversation System

DuoTalk is a comprehensive Python package for creating engaging multi-agent voice conversations with customizable personas, conversation modes, and easy integration capabilities. Built on top of LiveKit and Google Gemini, it provides a powerful yet simple API for generating dynamic conversations between AI agents with distinct personalities.

🌟 Features

• 🎭 Rich Persona Library: 14+ pre-defined personas (Optimist, Skeptic, Pragmatist, etc.)
• 🗣️ Multiple Conversation Modes: Debate, Roundtable, Interview, Panel, Socratic, and more
• 🎙️ Voice Integration: Full voice synthesis using Google Gemini's native audio
• ⚡ Easy Setup: Simple pip installation and intuitive API
• 🔧 Highly Customizable: Create custom personas, modes, and conversation flows
• 📊 Analytics: Built-in conversation metrics and performance tracking
• 🖥️ CLI Interface: Command-line tool for quick conversations
• 📝 Conversation Logging: Automatic conversation transcription and analysis
• 🎯 Multiple Use Cases: Education, brainstorming, testing, entertainment

🚀 Quick Start

Installation

pip install duotalk

Or using uv:

uv add duotalk

Environment Setup

Create a .env file with your API keys:

GEMINI_API_KEY=your_gemini_api_key_here
# Optional for production LiveKit usage
LIVEKIT_API_KEY=your_livekit_key
LIVEKIT_API_SECRET=your_livekit_secret

Basic Usage

import asyncio
from duotalk import create_debate

async def main():
    # Create a debate conversation
    runner = await create_debate(
        topic="Should AI replace human teachers?",
        max_turns=10
    )
    
    # Start the conversation
    await runner.start()

asyncio.run(main())

Using the CLI

# Start a debate conversation
duotalk debate -t "Pineapple on pizza"

# Friendly chat with custom personas
duotalk chat -t "Weekend plans" -p optimist,enthusiast

# Roundtable discussion with 4 participants
duotalk roundtable -t "Climate change solutions" -a 4

# Interview format
duotalk interview -t "AI ethics" --interviewer journalist --interviewee expert

# Expert panel discussion
duotalk panel -t "Space exploration" -a 5

# List available personas
duotalk personas

# Use different LiveKit modes
duotalk debate -t "Remote work" --mode dev      # Development mode
duotalk debate -t "Remote work" --mode console  # Console mode (default)
duotalk debate -t "Remote work" --mode start    # Production mode

# Get help
duotalk --help
duotalk debate --help

---

🌟 Overview

DuoTalk brings AI conversations to life with two distinct AI audio agents powered by Google Gemini-realtime and LiveKit. Watch as they engage in real-time voice conversations, whether collaborating in friendly discussions or debating opposing viewpoints on any topic you choose.

✨ Features

Feature	Description
🎭 Dual & Quad AI Voice Agents	Two or four agents with unique voices and personas
💬 Conversation Modes	Choose between friendly discussion, debate, or roundtable format
🌀 Roundtable Feature	Four agents share diverse perspectives in a dynamic roundtable
🎯 Custom Topics	Specify any topic for dynamic conversations
🔊 Real-Time Audio	Natural spoken dialogue using Gemini's latest models
🛡️ Robust Error Handling	Smart retry logic and graceful error recovery
🎪 Voice Personas	Distinct voices: Puck (optimist, pragmatist) & Charon (skeptic, theorist)
🎬 YouTube Integration	AI-powered YouTube video summarization with voice playback
🔄 Rate Limiting Resilience	Exponential backoff retry logic for API rate limits
🎵 Enhanced TTS	Robust text-to-speech with multiple fallback mechanisms

🆕 Recent Improvements (v1.0.5)

🎬 AI-Powered YouTube Summarization

• Google Gemini 2.5 Flash Lite integration for intelligent video analysis
• Automatic transcript extraction with robust error handling
• Customizable summary depth (short/detailed) based on user preference
• Voice narration of summaries using enhanced TTS system

🔊 Enhanced Voice System

• Robust TTS engine with comprehensive error handling
• pygame audio initialization checks and fallback mechanisms
• Windows-specific audio optimizations for better compatibility
• Proper resource cleanup to prevent audio system conflicts

🛡️ Rate Limiting & Resilience

• Exponential backoff retry logic for YouTube API rate limits (429 errors)
• Progressive wait times with intelligent retry strategies
• Comprehensive logging for debugging and monitoring
• Graceful degradation when services are temporarily unavailable

🐛 Bug Fixes

• Fixed single agent chat mode - no more unwanted multi-agent conversations
• Improved error handling across all conversation types
• Enhanced session management for better stability

🏗️ Code Architecture

📋 Requirements

Prerequisites for running DuoTalk

• 🐍 Python 3.8+
• 🔗 LiveKit Agents SDK
• 🧠 Google Gemini API

🚀 Quick Setup

1️⃣ Clone & Navigate

git clone https://github.com/AbhyudayPatel/DuoTalk.git
cd DuoTalk

2️⃣ Install Dependencies

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

3️⃣ Environment Configuration

Create a .env file in your project root:

# Add your Google Gemini API key
GOOGLE_API_KEY=your_gemini_api_key_here

💡 Tip: Get your API key from Google AI Studio

🎮 Usage

🏃‍♂️ Starting DuoTalk

# For 2 agents (friendly/discussion/debate):
python dual_voice_agents.py console
# For 4 agents (roundtable/friendly/debate):
python four_agents_duotalk.py console

📝 Interactive Setup

Step 1: 🎯 Choose Your Topic

Enter the topic for the conversation: _

Examples:

• The future of AI and robotics
• Climate change solutions
• Space exploration and Mars colonization
• The ethics of genetic engineering

Step 2: 🎭 Select Conversation Mode

Select conversation mode:
1. Friendly discussion (2 agents)
2. Debate format (2 agents)
3. Roundtable discussion (4 agents)
Enter your choice (1, 2, or 3): _

Mode	🤝 Friendly Discussion	⚔️ Debate Format	🌀 Roundtable
Style	Collaborative & supportive	Opposing viewpoints	Diverse perspectives
Tone	Encouraging dialogue	Direct & contrary	Dynamic & engaging
Personas	Agent1 & Agent2	Optimist vs Skeptic	Optimist, Skeptic, Pragmatist, Theorist
Voices	Puck & Charon	Puck & Charon	Puck & Charon (multiple roles)

⚙️ Configuration

🔧 Customization Options

Setting	Default	How to Change
🔄 Max Turns	12 turns	Modify max_turns in ConversationState
🎤 Agent Voices	Puck & Charon	Update voice parameters in code
🤖 AI Model	gemini-2.5-flash-preview-native-audio-dialog	Change model string
💬 Response Length	One-line responses	Modify instructions in DualPersonaAgent

🧩 Core Components

Component	🎯 Purpose
ConversationState	📊 Manages conversation state and settings
DualPersonaAgent	🎭 Main agent class with dual persona support
get_conversation_mode()	📝 Handles user input for conversation mode
run_friendly_conversation()	🤝 Manages friendly discussion flow
run_debate_conversation()	⚔️ Manages debate flow with optimist/skeptic roles
safe_generate_reply()	🛡️ Handles responses with error handling and retries

🛡️ Error Handling & Reliability

DuoTalk is built with enterprise-grade reliability:

🔍 Comprehensive Error Management

Feature	Description
📊 Session Health Monitoring	Real-time health checks
🔄 Automatic Retries	Smart retry logic for failed responses
🧹 Graceful Cleanup	Proper resource management
📝 Detailed Logging	Comprehensive debugging information
⏱️ Timeout Protection	Prevents hanging operations
🔧 Recovery Mechanisms	Automatic error recovery

📄 License

MIT License - See LICENSE file for details

Experience the future of AI conversation today!