soundflare 1.0.2
Soundflare Observe SDK - Voice Analytics for AI Agents
License: MIT
Requires Python: >=3.9

﻿# Soundflare – Voice AI Observability Platform
 
<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-v3.9+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/soundflare.svg)](https://badge.fury.io/py/soundflare)

**Professional voice analytics and observability for AI agents. Monitor, analyze, and improve your voice AI applications with comprehensive tracking and actionable insights.**

[🚀 Get Started](#quick-start) • [ Documentation](#documentation) • [✨ Features](#features)

</div>

---

## Features

- **🔍 Real-time Session Monitoring** - Track every voice interaction with comprehensive analytics
- **💰 Cost Tracking** - Monitor STT, TTS, and LLM costs across all providers
- **⚡ Performance Metrics** - Analyze latency, response times, and quality scores
- **🎯 Turn-by-Turn Analytics** - Detailed conversation turn tracking with full context
- **📊 OpenTelemetry Integration** - Native OTEL support for distributed tracing
- **🐛 Bug Reporting System** - Built-in user feedback collection during sessions
- **🔧 Easy Integration** - One-line SDK integration with LiveKit agents
- **📈 Usage Metrics** - Track token usage, API calls, and session duration
- **🎙️ Voice Analytics** - STT, TTS, LLM, and VAD metrics tracking

## Quick Start

### Installation

```bash
pip install soundflare
```

### Environment Setup

Create a `.env` file in your project root:

```env
# Soundflare Configuration
SOUNDFLARE_API_KEY=your_api_key_here
SOUNDFLARE_HOST_URL=your_host_url_here
```

### Basic Integration

```python
from dotenv import load_dotenv
import os
from soundflare import LivekitObserve

# Load environment variables
load_dotenv()

# Initialize observability
soundflare = LivekitObserve(
    agent_id="your-agent-id",
    apikey=os.getenv("SOUNDFLARE_API_KEY"),
    host_url=os.getenv("SOUNDFLARE_HOST_URL"),
    enable_otel=True  # Enable OpenTelemetry integration
)

# Wrap your LiveKit session
session = AgentSession(...)
session_id = soundflare.start_session(session, phone_number="+1234567890")

# Ensure data is exported on shutdown
async def soundflare_shutdown():
    await soundflare.export(session_id)

ctx.add_shutdown_callback(soundflare_shutdown)
await session.start(...)
```

### Advanced Features

#### Bug Reporting

Enable built-in bug reporting to collect user feedback during sessions:

```python
soundflare = LivekitObserve(
    agent_id="your-agent-id",
    apikey=os.getenv("SOUNDFLARE_API_KEY"),
    host_url=os.getenv("SOUNDFLARE_HOST_URL"),
    bug_reports_enable=True,
    bug_reports_config={
        'bug_start_command': ['feedback start', 'report issue'],
        'bug_end_command': ['feedback over', 'done reporting'],
        'response': 'Please tell me the issue?',
        'continuation_prefix': 'So, as I was saying, ',
        'debug': False
    }
)
```

#### OpenTelemetry Integration

Soundflare automatically integrates with OpenTelemetry for distributed tracing:

```python
from opentelemetry import trace

# SDK automatically creates spans for:
# - Session lifecycle
# - STT operations
# - LLM calls
# - TTS generation
# - User turns and agent responses

# Access spans data
soundflare = LivekitObserve(
    agent_id="your-agent-id",
    apikey=os.getenv("SOUNDFLARE_API_KEY"),
    host_url=os.getenv("SOUNDFLARE_HOST_URL"),
    enable_otel=True
)
```

## What You Can Track

| Metric | Description | Details |
|--------|-------------|---------|
| **Latency** | Response times for each component | STT, TTS, LLM processing times |
| **Costs** | Token usage and billing | Automatic cost calculation for major providers |
| **Transcripts** | Full conversation history | User input and agent responses |
| **Quality** | Transcription accuracy | Audio duration, confidence scores |
| **Sessions** | Call metadata | Duration, timestamps, phone numbers |
| **Turns** | Conversation flow | Turn-by-turn analysis with context |
| **Tool Calls** | Agent function executions | Track agent tool usage and results |

## Use Cases

- **Production Monitoring** - Keep voice AI applications running smoothly
- **Cost Optimization** - Identify expensive operations and optimize spending
- **Quality Assurance** - Review call transcripts and agent responses
- **Performance Debugging** - Diagnose latency issues and bottlenecks
- **User Feedback** - Collect and analyze bug reports during calls
- **Distributed Tracing** - Track requests across microservices

## Architecture

Soundflare SDK provides:

- **Lightweight Python SDK** - Minimal overhead data collection
- **Async Support** - Non-blocking data transmission
- **Event-Driven** - Hooks into LiveKit agent lifecycle
- **Metric Collection** - Comprehensive STT/TTS/LLM metrics
- **Session Management** - Automatic session tracking and cleanup

## Technology Stack

- **Core:** Python 3.9+, asyncio
- **Dependencies:** 
  - `livekit-agents` - Voice agent framework
  - `requests` - HTTP client for data transmission
  - `python-dotenv` - Environment configuration
- **Integrations:** OpenTelemetry, LiveKit

## Documentation

### Core Components

#### LivekitObserve

Main class for observability integration.

**Parameters:**
- `agent_id` (str): Unique identifier for your agent
- `apikey` (str, optional): API key for authentication
- `host_url` (str, optional): Host URL for data export
- `bug_reports_enable` (bool): Enable bug reporting feature
- `bug_reports_config` (dict): Configuration for bug reporting
- `enable_otel` (bool): Enable OpenTelemetry integration

**Methods:**
- `start_session(session, phone_number=None)`: Initialize session tracking
- `export(session_id)`: Export session data
- `handle_bug_report(user_input, session)`: Process user feedback

### Session Tracking

The SDK automatically tracks:
- Session start/end times
- Conversation turns
- STT/TTS/LLM metrics
- Cost calculations
- OpenTelemetry spans
- Tool calls and executions

### Metrics Collected

**STT Metrics:**
- Audio duration
- Latency
- Model name
- Streaming status
- Cost per request

**LLM Metrics:**
- Prompt tokens
- Completion tokens
- Latency
- Model name
- Cost per request

**TTS Metrics:**
- Characters generated
- Audio duration
- Latency
- Model name
- Cost per request

## Configuration

### Environment Variables

```env
# Required
SOUNDFLARE_API_KEY=your_api_key

# Optional
SOUNDFLARE_HOST_URL=https://your-host.com
```

### Bug Report Configuration

```python
bug_reports_config = {
    'bug_start_command': ['feedback start'],  # Trigger phrases
    'bug_end_command': ['feedback over'],      # End phrases
    'response': 'Please tell me the issue?',   # Agent response
    'continuation_prefix': 'So, as I was saying, ',  # Resume prefix
    'fallback_message': 'So, as I was saying,',      # Fallback text
    'collection_prompt': '',                   # Custom prompt
    'debug': False                             # Debug logging
}
```
## Support

- **📧 Email:** support@trillet.ai
- **🐛 Bug Reports:** [GitHub Issues](https://github.com/TrilletAI/soundflare-sdk/issues)
- **💡 Feature Requests:** [GitHub Discussions](https://github.com/TrilletAI/soundflare-sdk/discussions)

## Enterprise

Need enterprise features like custom deployments or dedicated support? 

**Contact us:** support@trillet.ai

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with ❤️ by the Trillet AI team
- Powered by LiveKit for real-time voice infrastructure
- Inspired by modern observability platforms

---

<div align="center">

**⭐ If Soundflare helps your voice AI applications, consider giving us a star!**

</div>