# 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
```bash
pip install duotalk
```
Or using uv:
```bash
uv add duotalk
```
### Environment Setup
Create a `.env` file with your API keys:
```env
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
```python
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
```bash
# 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
```
*Experience the future of AI interaction with two agents engaging in dynamic voice conversations*
</div>
---
## 🌟 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) |
## 🏗️ Code Architecture
## 📋 Requirements
> **Prerequisites for running DuoTalk**
- 🐍 **Python 3.8+**
- 🔗 **[LiveKit Agents SDK](https://github.com/livekit/agents)**
- 🧠 **[Google Gemini API](https://aistudio.google.com/)**
## 🚀 Quick Setup
### 1️⃣ Clone & Navigate
```bash
git clone https://github.com/AbhyudayPatel/DuoTalk.git
cd DuoTalk
```
### 2️⃣ Install Dependencies
```bash
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```
### 3️⃣ Environment Configuration
Create a `.env` file in your project root:
```env
# Add your Google Gemini API key
GOOGLE_API_KEY=your_gemini_api_key_here
```
> 💡 **Tip:** Get your API key from [Google AI Studio](https://aistudio.google.com/)
## 🎮 Usage
### 🏃♂️ Starting DuoTalk
```bash
# 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
<details>
<summary>🔧 <strong>Customization Options</strong></summary>
| 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` |
</details>
### 🧩 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**:
<details>
<summary>🔍 <strong>Comprehensive Error Management</strong></summary>
| 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 |
</details>
## 📄 License
**MIT License** - See LICENSE file for details
*Experience the future of AI conversation today!*
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "duotalk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "voice, ai, conversation, agents, livekit, gemini",
"author": null,
"author_email": "Abhyuday Patel <patelabhyuday09@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/95/31/eb0d13812f2f4b8e5094e5d2e87e28bdba436e4a24829f6a5190e54b7b75/duotalk-1.0.4.tar.gz",
"platform": null,
"description": "# DuoTalk \ud83c\udfad\r\n\r\n**Advanced Multi-Agent Voice Conversation System**\r\n\r\nDuoTalk 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.\r\n\r\n## \ud83c\udf1f Features\r\n\r\n- **\ud83c\udfad Rich Persona Library**: 14+ pre-defined personas (Optimist, Skeptic, Pragmatist, etc.)\r\n- **\ud83d\udde3\ufe0f Multiple Conversation Modes**: Debate, Roundtable, Interview, Panel, Socratic, and more\r\n- **\ud83c\udf99\ufe0f Voice Integration**: Full voice synthesis using Google Gemini's native audio\r\n- **\u26a1 Easy Setup**: Simple pip installation and intuitive API\r\n- **\ud83d\udd27 Highly Customizable**: Create custom personas, modes, and conversation flows\r\n- **\ud83d\udcca Analytics**: Built-in conversation metrics and performance tracking\r\n- **\ud83d\udda5\ufe0f CLI Interface**: Command-line tool for quick conversations\r\n- **\ud83d\udcdd Conversation Logging**: Automatic conversation transcription and analysis\r\n- **\ud83c\udfaf Multiple Use Cases**: Education, brainstorming, testing, entertainment\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install duotalk\r\n```\r\n\r\nOr using uv:\r\n```bash\r\nuv add duotalk\r\n```\r\n\r\n### Environment Setup\r\n\r\nCreate a `.env` file with your API keys:\r\n```env\r\nGEMINI_API_KEY=your_gemini_api_key_here\r\n# Optional for production LiveKit usage\r\nLIVEKIT_API_KEY=your_livekit_key\r\nLIVEKIT_API_SECRET=your_livekit_secret\r\n```\r\n\r\n### Basic Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom duotalk import create_debate\r\n\r\nasync def main():\r\n # Create a debate conversation\r\n runner = await create_debate(\r\n topic=\"Should AI replace human teachers?\",\r\n max_turns=10\r\n )\r\n \r\n # Start the conversation\r\n await runner.start()\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n### Using the CLI\r\n\r\n```bash\r\n# Start a debate conversation\r\nduotalk debate -t \"Pineapple on pizza\"\r\n\r\n# Friendly chat with custom personas\r\nduotalk chat -t \"Weekend plans\" -p optimist,enthusiast\r\n\r\n# Roundtable discussion with 4 participants\r\nduotalk roundtable -t \"Climate change solutions\" -a 4\r\n\r\n# Interview format\r\nduotalk interview -t \"AI ethics\" --interviewer journalist --interviewee expert\r\n\r\n# Expert panel discussion\r\nduotalk panel -t \"Space exploration\" -a 5\r\n\r\n# List available personas\r\nduotalk personas\r\n\r\n# Use different LiveKit modes\r\nduotalk debate -t \"Remote work\" --mode dev # Development mode\r\nduotalk debate -t \"Remote work\" --mode console # Console mode (default)\r\nduotalk debate -t \"Remote work\" --mode start # Production mode\r\n\r\n# Get help\r\nduotalk --help\r\nduotalk debate --help\r\n```\r\n\r\n*Experience the future of AI interaction with two agents engaging in dynamic voice conversations*\r\n\r\n\r\n\r\n\r\n\r\n\r\n</div>\r\n\r\n---\r\n\r\n## \ud83c\udf1f Overview\r\n\r\nDuoTalk 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.\r\n\r\n## \u2728 Features\r\n\r\n| Feature | Description |\r\n|---------|-------------|\r\n| \ud83c\udfad **Dual & Quad AI Voice Agents** | Two or four agents with unique voices and personas |\r\n| \ud83d\udcac **Conversation Modes** | Choose between friendly discussion, debate, or roundtable format |\r\n| \ud83c\udf00 **Roundtable Feature** | Four agents share diverse perspectives in a dynamic roundtable |\r\n| \ud83c\udfaf **Custom Topics** | Specify any topic for dynamic conversations |\r\n| \ud83d\udd0a **Real-Time Audio** | Natural spoken dialogue using Gemini's latest models |\r\n| \ud83d\udee1\ufe0f **Robust Error Handling** | Smart retry logic and graceful error recovery |\r\n| \ud83c\udfaa **Voice Personas** | Distinct voices: **Puck** (optimist, pragmatist) & **Charon** (skeptic, theorist) |\r\n\r\n## \ud83c\udfd7\ufe0f Code Architecture\r\n\r\n\r\n## \ud83d\udccb Requirements\r\n\r\n> **Prerequisites for running DuoTalk**\r\n\r\n- \ud83d\udc0d **Python 3.8+**\r\n- \ud83d\udd17 **[LiveKit Agents SDK](https://github.com/livekit/agents)**\r\n- \ud83e\udde0 **[Google Gemini API](https://aistudio.google.com/)**\r\n\r\n## \ud83d\ude80 Quick Setup\r\n\r\n### 1\ufe0f\u20e3 Clone & Navigate\r\n```bash\r\ngit clone https://github.com/AbhyudayPatel/DuoTalk.git\r\ncd DuoTalk\r\n```\r\n\r\n### 2\ufe0f\u20e3 Install Dependencies\r\n```bash\r\npython -m venv venv\r\nvenv\\Scripts\\activate\r\npip install -r requirements.txt\r\n```\r\n\r\n### 3\ufe0f\u20e3 Environment Configuration\r\nCreate a `.env` file in your project root:\r\n```env\r\n# Add your Google Gemini API key\r\nGOOGLE_API_KEY=your_gemini_api_key_here\r\n```\r\n\r\n> \ud83d\udca1 **Tip:** Get your API key from [Google AI Studio](https://aistudio.google.com/)\r\n\r\n## \ud83c\udfae Usage\r\n\r\n### \ud83c\udfc3\u200d\u2642\ufe0f Starting DuoTalk\r\n```bash\r\n# For 2 agents (friendly/discussion/debate):\r\npython dual_voice_agents.py console\r\n# For 4 agents (roundtable/friendly/debate):\r\npython four_agents_duotalk.py console\r\n```\r\n\r\n### \ud83d\udcdd Interactive Setup\r\n\r\n#### Step 1: \ud83c\udfaf Choose Your Topic\r\n```\r\nEnter the topic for the conversation: _\r\n```\r\n**Examples:**\r\n- `The future of AI and robotics`\r\n- `Climate change solutions`\r\n- `Space exploration and Mars colonization`\r\n- `The ethics of genetic engineering`\r\n\r\n#### Step 2: \ud83c\udfad Select Conversation Mode\r\n```\r\nSelect conversation mode:\r\n1. Friendly discussion (2 agents)\r\n2. Debate format (2 agents)\r\n3. Roundtable discussion (4 agents)\r\nEnter your choice (1, 2, or 3): _\r\n```\r\n\r\n| Mode | \ud83e\udd1d Friendly Discussion | \u2694\ufe0f Debate Format | \ud83c\udf00 Roundtable |\r\n|------|------------------------|-------------------|-------------------|\r\n| **Style** | Collaborative & supportive | Opposing viewpoints | Diverse perspectives |\r\n| **Tone** | Encouraging dialogue | Direct & contrary | Dynamic & engaging |\r\n| **Personas** | Agent1 & Agent2 | Optimist vs Skeptic | Optimist, Skeptic, Pragmatist, Theorist |\r\n| **Voices** | Puck & Charon | Puck & Charon | Puck & Charon (multiple roles) |\r\n\r\n## \u2699\ufe0f Configuration\r\n\r\n<details>\r\n<summary>\ud83d\udd27 <strong>Customization Options</strong></summary>\r\n\r\n| Setting | Default | How to Change |\r\n|---------|---------|---------------|\r\n| \ud83d\udd04 **Max Turns** | 12 turns | Modify `max_turns` in `ConversationState` |\r\n| \ud83c\udfa4 **Agent Voices** | Puck & Charon | Update voice parameters in code |\r\n| \ud83e\udd16 **AI Model** | `gemini-2.5-flash-preview-native-audio-dialog` | Change model string |\r\n| \ud83d\udcac **Response Length** | One-line responses | Modify instructions in `DualPersonaAgent` |\r\n\r\n</details>\r\n\r\n\r\n### \ud83e\udde9 Core Components\r\n\r\n| Component | \ud83c\udfaf Purpose |\r\n|-----------|------------|\r\n| `ConversationState` | \ud83d\udcca Manages conversation state and settings |\r\n| `DualPersonaAgent` | \ud83c\udfad Main agent class with dual persona support |\r\n| `get_conversation_mode()` | \ud83d\udcdd Handles user input for conversation mode |\r\n| `run_friendly_conversation()` | \ud83e\udd1d Manages friendly discussion flow |\r\n| `run_debate_conversation()` | \u2694\ufe0f Manages debate flow with optimist/skeptic roles |\r\n| `safe_generate_reply()` | \ud83d\udee1\ufe0f Handles responses with error handling and retries |\r\n\r\n## \ud83d\udee1\ufe0f Error Handling & Reliability\r\n\r\nDuoTalk is built with **enterprise-grade reliability**:\r\n\r\n<details>\r\n<summary>\ud83d\udd0d <strong>Comprehensive Error Management</strong></summary>\r\n\r\n| Feature | Description |\r\n|---------|-------------|\r\n| \ud83d\udcca **Session Health Monitoring** | Real-time health checks |\r\n| \ud83d\udd04 **Automatic Retries** | Smart retry logic for failed responses |\r\n| \ud83e\uddf9 **Graceful Cleanup** | Proper resource management |\r\n| \ud83d\udcdd **Detailed Logging** | Comprehensive debugging information |\r\n| \u23f1\ufe0f **Timeout Protection** | Prevents hanging operations |\r\n| \ud83d\udd27 **Recovery Mechanisms** | Automatic error recovery |\r\n\r\n</details>\r\n\r\n\r\n## \ud83d\udcc4 License\r\n\r\n**MIT License** - See LICENSE file for details\r\n\r\n*Experience the future of AI conversation today!*\r\n\r\n</div>\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Advanced multi-agent voice conversation system with customizable personas and modes",
"version": "1.0.4",
"project_urls": {
"Documentation": "https://duotalk.readthedocs.io",
"Homepage": "https://github.com/AbhyudayPatel/DuoTalk",
"Issues": "https://github.com/AbhyudayPatel/DuoTalk/issues",
"Repository": "https://github.com/AbhyudayPatel/DuoTalk"
},
"split_keywords": [
"voice",
" ai",
" conversation",
" agents",
" livekit",
" gemini"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15c3b5bd251436d1f4571966c27491ffd33daa25eb77e7f1273e68a0768e50b8",
"md5": "6709bacd8196aa56c360f4f7f579811f",
"sha256": "edc92de271faad6e3a709cf018230449b5097893a657d721a51b748c8035cbd8"
},
"downloads": -1,
"filename": "duotalk-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6709bacd8196aa56c360f4f7f579811f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 71864,
"upload_time": "2025-08-22T06:30:00",
"upload_time_iso_8601": "2025-08-22T06:30:00.941549Z",
"url": "https://files.pythonhosted.org/packages/15/c3/b5bd251436d1f4571966c27491ffd33daa25eb77e7f1273e68a0768e50b8/duotalk-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9531eb0d13812f2f4b8e5094e5d2e87e28bdba436e4a24829f6a5190e54b7b75",
"md5": "ab6918efbb7d3e83653a68c4eb9c3302",
"sha256": "f3009a2ccc662cee545151663b2ccc795f08771d52e518f546300ad130fe3dc4"
},
"downloads": -1,
"filename": "duotalk-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "ab6918efbb7d3e83653a68c4eb9c3302",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 62252,
"upload_time": "2025-08-22T06:30:04",
"upload_time_iso_8601": "2025-08-22T06:30:04.150782Z",
"url": "https://files.pythonhosted.org/packages/95/31/eb0d13812f2f4b8e5094e5d2e87e28bdba436e4a24829f6a5190e54b7b75/duotalk-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 06:30:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AbhyudayPatel",
"github_project": "DuoTalk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "livekit",
"specs": []
},
{
"name": "google.genai",
"specs": []
},
{
"name": "livekit-agents",
"specs": []
},
{
"name": "livekit-api",
"specs": []
},
{
"name": "python-dotenv",
"specs": []
},
{
"name": "google-genai",
"specs": []
},
{
"name": "livekit-plugins-google",
"specs": []
}
],
"lcname": "duotalk"
}
JSON
