Easy Sonic

A high-level Python SDK for Amazon Nova 2 Sonic speech-to-speech conversations.

Build voice-enabled AI applications in just a few lines of code.

Features

• Simple API: Create a voice assistant in 3 lines of code
• Batteries Included: Built-in microphone and speaker handling
• Tool Support: Define functions the AI can call with simple decorators
• Callbacks: Monitor conversations in real-time
• Multi-language: Support for 10+ languages with polyglot voices
• Configurable: Sensible defaults with full customization options

Quick Start

import asyncio
from easy_sonic import Sonic

async def main():
    client = Sonic()
    await client.chat("You are a helpful assistant.")

asyncio.run(main())

That's it! Start talking to your AI assistant.

Installation

pip install easy-sonic

System Dependencies

Easy Sonic uses PyAudio for audio. Install system dependencies:

macOS:

brew install portaudio

Ubuntu/Debian:

sudo apt-get install portaudio19-dev

Prerequisites

1. AWS Account with Bedrock access
2. AWS Credentials configured:

   export AWS_ACCESS_KEY_ID=your_key
   export AWS_SECRET_ACCESS_KEY=your_secret
   export AWS_DEFAULT_REGION=us-east-1

3. Microphone and speakers connected

Usage Examples

With Callbacks

await client.chat(
    system_prompt="You are helpful.",
    on_user_transcript=lambda t: print(f"User: {t}"),
    on_assistant_text=lambda t: print(f"Assistant: {t}"),
)

With Tools

@client.tool
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    return f"Sunny in {city}"

await client.chat("You are a weather assistant.")

Custom Configuration

client = Sonic(
    region="us-east-1",
    voice="matthew",
    language="en-US",
    temperature=0.7,
)

Text Input Mode

await client.chat(
    system_prompt="You are helpful.",
    audio_input=False,  # Type instead of speak
)

Configuration Options

Option	Default	Description
region	"us-east-1"	AWS region
voice	"tiffany"	Voice (tiffany, matthew, amy)
language	"en-US"	Language code
max_tokens	1024	Max response tokens
temperature	0.7	Creativity (0.0-1.0)
top_p	0.9	Nucleus sampling

Callbacks

Callback	Description
on_user_transcript	User speech transcribed
on_assistant_text	Assistant text generated
on_assistant_audio	Assistant audio chunk
on_turn_start	New turn begins
on_turn_end	Turn completes
on_tool_call	Tool invoked
on_tool_result	Tool returns
on_error	Error occurs

Supported Languages

• English (US, UK, India, Australia)
• French
• Italian
• German
• Spanish
• Portuguese
• Hindi

Documentation

• Getting Started
• Configuration Guide
• Callbacks Guide
• Tools Guide
• Audio Guide
• Examples
• Troubleshooting
• API Reference

Examples

The examples/ directory contains progressively complex examples:

Example	Description
01_minimal	Simplest possible app
02_callbacks	Using callbacks
03_tools	Function calling
04_text_mode	Text input
05_custom_audio	Custom audio sources
06_advanced	History, multi-language

Run an example:

cd examples/01_minimal
python hello_voice.py

Development

# Clone the repository
git clone https://github.com/your-repo/easy-sonic
cd easy-sonic

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run linting
uv run ruff check .
uv run mypy src/easy_sonic

License

MIT License - see LICENSE file.

Contributing

Contributions welcome! Please read the contributing guidelines first.

Acknowledgments

Built on top of Amazon Nova 2 Sonic and Amazon Bedrock.