### Install Cloud Quickstart Stack with pip

Source: https://github.com/telecmi/agents/blob/development/example/README.md

Installs the Piopiy-ai SDK with dependencies for a cloud-based quickstart stack, including OpenAI LLM, Deepgram ASR, Cartesia TTS, and Silero VAD. This command is suitable for users who want to leverage managed cloud services.

```bash
pip install "piopiy-ai[cartesia,deepgram,openai,silero]"
```

--------------------------------

### Install MiniMax TTS and Set API Key

Source: https://github.com/telecmi/agents/blob/development/docs/tts/minimax.md

Installs the piopiy-ai library with MiniMax support and sets the MINIMAX_API_KEY environment variable. This is the initial setup step for using the service.

```bash
pip install "piopiy-ai[minimax]"
export MINIMAX_API_KEY=your_key
```

--------------------------------

### Qwen LLM Service Setup

Source: https://github.com/telecmi/agents/blob/development/docs/llm/qwen.md

Instructions for installing the Qwen LLM package and setting up the necessary API key for authentication.

```APIDOC
## Installation and Authentication

### Description
Install the piopiy-ai library with Qwen support and set your Qwen API key as an environment variable.

### Method
Terminal commands and environment variable export.

### Endpoint
N/A

### Parameters
#### Environment Variables
- **QWEN_API_KEY** (string) - Required - Your API key for accessing the Qwen service.

### Request Example
```bash
pip install "piopiy-ai[qwen]"
export QWEN_API_KEY=your_key
```

### Response
N/A
```

--------------------------------

### MiniMax TTS Service Setup

Source: https://github.com/telecmi/agents/blob/development/docs/tts/minimax.md

Instructions for installing the necessary library and setting up the API key for the MiniMax TTS service.

```APIDOC
## MiniMax TTS Service Setup

### Description
This section outlines the prerequisites and initial setup for using the MiniMax Text-to-Speech service.

### Installation
Install the required library using pip:

```bash
pip install "piopiy-ai[minimax]"
```

### Authentication
Set your MiniMax API key as an environment variable:

```bash
export MINIMAX_API_KEY=your_key
```

### Parameters

*   **`api_key`** (string) - Required - API key for authentication.
*   **`base_url`** (string) - Optional - Override API base URL (default: `"https://api.minimax.io/v1/t2a_v2"`).
*   **`group_id`** (string) - Required - Group identifier.
*   **`model`** (string) - Optional - Model name to use (default: `"speech-02-turbo"`).
*   **`voice_id`** (string) - Optional - Voice identifier to use (default: `"Calm_Woman"`).
*   **`aiohttp_session`** (object) - Optional - Reuse existing aiohttp session.
*   **`sample_rate`** (integer) - Optional - Target audio sample rate.
*   **`params`** (object) - Optional - Provider specific options.

### Input Parameters

*   **`language`** (string) - Required - Language for synthesis.
*   **`speed`** (float) - Optional - Speech speed (0.5 to 2.0).
*   **`volume`** (integer) - Optional - Speech volume (0 to 10).
*   **`pitch`** (integer) - Optional - Pitch adjustment (-12 to 12).
*   **`emotion`** (string) - Optional - Emotional tone (e.g., `"happy"`, `"sad"`).
*   **`english_normalization`** (boolean) - Optional - Enable English text normalization.

### Request Example (Python SDK Initialization)

```python
import os
from piopiy.services.minimax.tts import MiniMaxHttpTTSService

tts = MiniMaxHttpTTSService(
    api_key=os.getenv("MINIMAX_API_KEY"),
    group_id="GROUP_ID",
    model="speech-02-turbo",
    voice_id="Calm_Woman",
    sample_rate=24000,
)
```
```

--------------------------------

### Install Chatterbox Dependencies with Pip

Source: https://github.com/telecmi/agents/blob/development/example/chatterbox/README.md

Installs the necessary Python packages for the Chatterbox client agent, including support for Deepgram, OpenAI, and Silero TTS engines. This command ensures all required libraries are available for the agent to function.

```bash
pip install "piopiy-ai[deepgram,openai,silero]" python-dotenv
```

--------------------------------

### OpenRouter LLM Service Setup

Source: https://github.com/telecmi/agents/blob/development/docs/llm/openrouter.md

This section outlines the installation process and how to set up the OpenRouter LLM service using the piopiy-ai library.

```APIDOC
## Installation and Setup

### Description
Install the piopiy-ai library with OpenRouter support and set your API key as an environment variable.

### Method
Bash and Python

### Installation Command
```bash
pip install "piopiy-ai[openrouter]"
```

### API Key Configuration
Set your OpenRouter API key in your environment variables:

```bash
export OPENROUTER_API_KEY=your_key
```

### Service Initialization
Initialize the `OpenRouterLLMService` with your API key and desired model.

```python
import os
from piopiy.services.openrouter.llm import OpenRouterLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

# Define input parameters for the LLM
params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={}
)

# Initialize the OpenRouter LLM service
service = OpenRouterLLMService(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    model="openai/gpt-4o-2024-11-20",
    params=params
)
```

### Optional Arguments for `OpenRouterLLMService`

- **model** (string): OpenRouter model name. Defaults to `openai/gpt-4o-2024-11-20`.
- **base_url** (string): Custom API endpoint, useful for self-hosted proxies.
- **organization** (string): ID used for multi-tenant setups.
- **project** (string): ID used for multi-tenant setups.
- **default_headers** (dict): Extra headers sent with each request.
- **retry_timeout_secs** (int): Request timeout in seconds.
- **retry_on_timeout** (bool): Retry once if a request times out.

### Input Parameters for `BaseOpenAILLMService.InputParams`

- **temperature** (float): Higher values produce more random outputs. Defaults to 0.7.
- **top_p** (float): Nucleus sampling; alternative to `temperature`. Defaults to 0.9.
- **frequency_penalty** (float): Discourage repeated tokens. Defaults to 0.5.
- **max_completion_tokens** (int): Cap the length of the LLM's reply. Defaults to 256.
- **extra** (dict): Dictionary for model-specific options. Defaults to {}.

### Customizing Endpoints and Headers

Customize `base_url` or `default_headers` when pointing the client to a proxy or self-hosted OpenRouter-compatible endpoint.

```python
service_custom = OpenRouterLLMService(
    api_key=os.getenv("OPENROUTER_API_KEY"),
    model="openai/gpt-4o-2024-11-20",
    base_url="http://localhost:8000/v1", # Example custom base URL
    default_headers={"X-Custom-Header": "value"} # Example custom headers
)
```
```

--------------------------------

### SambaNova LLM Service Setup

Source: https://github.com/telecmi/agents/blob/development/docs/llm/sambanova.md

Provides instructions for installing the necessary library, setting up authentication, and initializing the SambaNovaLLMService with custom parameters.

```APIDOC
## Installation and Authentication

### Description
Install the `piopiy-ai` library with SambaNova support and set your SambaNova API key as an environment variable.

### Commands

```bash
pip install "piopiy-ai[sambanova]"
export SAMBANOVA_API_KEY=your_key
```

## SambaNovaLLMService Initialization

### Description
Initialize the `SambaNovaLLMService` with your API key and desired model. You can also configure sampling and limit parameters.

### Method
```python
import os
from piopiy.services.sambanova.llm import SambaNovaLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

# Define input parameters for the LLM
params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={}
)

# Initialize the SambaNovaLLMService
service = SambaNovaLLMService(
    api_key=os.getenv("SAMBANOVA_API_KEY"),
    model="Llama-4-Maverick-17B-128E-Instruct",
    params=params
)
```

### Optional Arguments for `SambaNovaLLMService`

- `model` (string): SambaNova model name. Defaults to `Llama-4-Maverick-17B-128E-Instruct`.
- `base_url` (string): Custom API endpoint, useful for self-hosted proxies.
- `organization` (string): ID for multi-tenant setups.
- `project` (string): ID for multi-tenant setups.
- `default_headers` (dict): Extra headers sent with each request.
- `retry_timeout_secs` (int): Request timeout in seconds.
- `retry_on_timeout` (bool): Retry once if a request times out.

### Input Parameters for `BaseOpenAILLMService.InputParams`

- `temperature` (float): Higher values produce more random outputs. Defaults to 0.7.
- `top_p` (float): Nucleus sampling; alternative to `temperature`. Defaults to 0.9.
- `frequency_penalty` (float): Discourage repeated tokens. Defaults to 0.5.
- `max_completion_tokens` (int): Cap the length of the LLM's reply. Defaults to 256.
- `extra` (dict): Dictionary for model-specific options. 

### Custom Endpoints and Headers

Customize `base_url` or `default_headers` when pointing the client to a proxy or self-hosted SambaNova-compatible endpoint.
```

--------------------------------

### Ollama LLM Service Setup

Source: https://github.com/telecmi/agents/blob/development/docs/llm/ollama.md

This section covers the installation of the piopiy library with Ollama support and setting up the API key for authentication.

```APIDOC
## Installation and Authentication

### Description
Install the necessary library and set your Ollama API key as an environment variable.

### Method
```bash
pip install "piopiy-ai[ollama]"
export OLLAMA_API_KEY=your_key
```

### Request Body
Not applicable.

### Response
Not applicable.

```

--------------------------------

### Run Chatterbox Open-Source Example

Source: https://github.com/telecmi/agents/blob/development/example/README.md

Executes the 'chatterbox_ws.py' example, demonstrating a fully open-source voice stack running locally. It uses Ollama for LLM, Whisper for ASR, and Chatterbox for TTS, streaming speech via WebSockets.

```bash
python chatterbox/chatterbox_ws.py
```

--------------------------------

### MiniMax TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Provides an example of streaming audio from MiniMax TTS using piopiy-ai. Requires installation of the 'minimax' extra and setting the MINIMAX_API_KEY environment variable. The function streams audio chunks asynchronously.

```bash
pip install "piopiy-ai[minimax]"
export MINIMAX_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.minimax.tts import MiniMaxHttpTTSService

async def main():
    tts = MiniMaxHttpTTSService(api_key=os.getenv("MINIMAX_API_KEY"))
    async for chunk in tts.stream("Hello from MiniMax"):
        pass

asyncio.run(main())
```

--------------------------------

### Run Orpheus Pluggable VAD Example

Source: https://github.com/telecmi/agents/blob/development/example/README.md

Executes the 'orpheus.py' example, demonstrating pluggable VAD dictionary syntax with an open-source TTS engine. It uses Ollama for LLM, Whisper for ASR, and Orpheus for TTS.

```bash
python orpheus/orpheus.py
```

--------------------------------

### ElevenLabs TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Shows how to stream audio from ElevenLabs TTS using piopiy-ai. Requires installation of the 'elevenlabs' extra and setting the ELEVENLABS_API_KEY environment variable. The example streams audio chunks asynchronously.

```bash
pip install "piopiy-ai[elevenlabs]"
export ELEVENLABS_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.elevenlabs.tts import ElevenLabsTTSService

async def main():
    tts = ElevenLabsTTSService(api_key=os.getenv("ELEVENLABS_API_KEY"))
    async for chunk in tts.stream("Hello from ElevenLabs"):
        pass

asyncio.run(main())
```

--------------------------------

### Install Rime TTS and Set API Key (Bash)

Source: https://github.com/telecmi/agents/blob/development/docs/tts/rime.md

This snippet shows how to install the Rime TTS package using pip and set the RIME_API_KEY environment variable for authentication.

```bash
pip install "piopiy-ai[rime]"
export RIME_API_KEY=your_key
```

--------------------------------

### Install AsyncAI TTS and Set API Key (Bash)

Source: https://github.com/telecmi/agents/blob/development/docs/tts/asyncai.md

This snippet shows how to install the piopiy-ai library with AsyncAI support using pip and how to set the ASYNCAI_API_KEY environment variable for authentication.

```bash
pip install "piopiy-ai[asyncai]"
export ASYNCAI_API_KEY=your_key
```

--------------------------------

### Run Basic Voice Loop Example

Source: https://github.com/telecmi/agents/blob/development/example/README.md

Executes the 'basic.py' example script, which demonstrates a minimal voice loop using the VoiceAgent.Action API. It typically uses OpenAI for LLM, Deepgram for ASR, Cartesia for TTS, and Silero for VAD.

```bash
python basic.py
```

--------------------------------

### Google TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Provides an example of streaming audio from Google TTS using piopiy-ai. Requires installation of the 'google' extra and setting the GOOGLE_API_KEY environment variable. The function streams audio chunks asynchronously.

```bash
pip install "piopiy-ai[google]"
export GOOGLE_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.google.tts import GoogleHttpTTSService

async def main():
    tts = GoogleHttpTTSService(api_key=os.getenv("GOOGLE_API_KEY"))
    async for chunk in tts.stream("Hello from Google"):
        pass

asyncio.run(main())
```

--------------------------------

### Run Chatterbox Client Agent with Python

Source: https://github.com/telecmi/agents/blob/development/example/chatterbox/README.md

Executes the Chatterbox client agent using a Python script. This command starts the agent, which will then connect to the Chatterbox TTS server and begin processing voice interactions.

```bash
python chatterbox_ws.py
```

--------------------------------

### Run Kokoro Offline TTS Example

Source: https://github.com/telecmi/agents/blob/development/example/README.md

Executes the 'kokoro.py' example, which features fully offline TTS using Kokoro ONNX models. This example utilizes Ollama for LLM and Whisper for ASR, running locally.

```bash
python kokoro/kokoro.py
```

--------------------------------

### Run Weather Tool-Calling Example

Source: https://github.com/telecmi/agents/blob/development/example/README.md

Executes the 'weather.py' example script, showcasing a function-calling workflow for a weather tool. This example typically utilizes OpenAI for LLM, Deepgram for ASR, and Cartesia for TTS.

```bash
python function_calling/weather.py
```

--------------------------------

### AWS Bedrock LLM Service Setup and Usage

Source: https://github.com/telecmi/agents/blob/development/docs/llm/aws.md

This section details the installation, authentication, and initialization of the AWSBedrockLLMService, along with an explanation of its input parameters for controlling LLM behavior.

```APIDOC
## AWS Bedrock LLM Service Setup and Usage

### Description
This section covers the installation, authentication, and initialization of the `AWSBedrockLLMService` for interacting with AWS Bedrock.

### Installation
```bash
pip install "piopiy-ai[aws]"
```

### Authentication
Set your AWS credentials as environment variables:

```bash
export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
```

### Initialization
Initialize the service with model details and parameters:

```python
import os
from piopiy.services.aws.llm import AWSBedrockLLMService

# Define input parameters for the LLM
params = AWSBedrockLLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=256,
    stop_sequences=["\n\n"],
    latency="standard",
    additional_model_request_fields={ "temperature": 0.5 } # Example of model-specific field
)

# Initialize the AWSBedrockLLMService
service = AWSBedrockLLMService(
    model="amazon.nova-pro-v1:0",
    aws_access_key=os.getenv("AWS_ACCESS_KEY_ID"),
    aws_secret_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    aws_region="us-east-1",
    params=params
)
```

### Optional Arguments for `AWSBedrockLLMService`

- `aws_access_key` (string) - Optional - Your AWS access key ID. If omitted, IAM roles are used.
- `aws_secret_key` (string) - Optional - Your AWS secret access key. If omitted, IAM roles are used.
- `aws_session_token` (string) - Optional - Token for temporary AWS credentials.
- `aws_region` (string) - Optional - The AWS region where the Bedrock service is located. Defaults to `us-east-1`.
- `client_config` (dict) - Optional - Custom configuration for the boto3 client.
- `retry_timeout_secs` (int) - Optional - Timeout in seconds for retrying requests.
- `retry_on_timeout` (bool) - Optional - Whether to retry once if a request times out.

### Input Parameters for `AWSBedrockLLMService.InputParams`

- `temperature` (float) - Optional - Controls randomness. Higher values increase randomness. Default: 0.7.
- `top_p` (float) - Optional - Nucleus sampling parameter. Alternative to `temperature`. Default: 0.9.
- `max_tokens` (int) - Optional - Maximum number of tokens in the generated response. Default: 256.
- `stop_sequences` (list[str]) - Optional - List of strings that will cause generation to stop.
- `latency` (str) - Optional - Latency mode, either `standard` or `optimized`. Default: `standard`.
- `additional_model_request_fields` (dict) - Optional - A dictionary for model-specific request options.

### Custom Clients

You can tune networking or retry behavior by providing a `client_config` dictionary during service initialization. For example:

```python
client_config = {
    'retries': {
        'max_attempts': 10,
        'mode': 'adaptive'
    }
}

service = AWSBedrockLLMService(
    model="amazon.nova-pro-v1:0",
    aws_access_key=os.getenv("AWS_ACCESS_KEY_ID"),
    aws_secret_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    aws_region="us-east-1",
    params=params,
    client_config=client_config
)
```
```

--------------------------------

### Install and Configure PlayHT TTS

Source: https://github.com/telecmi/agents/blob/development/docs/tts/playht.md

Installs the necessary piopiy library with PlayHT support and sets the PLAYHT_API_KEY environment variable for authentication. Ensure you replace 'your_key' with your actual PlayHT API key.

```bash
pip install "piopiy-ai[playht]"
export PLAYHT_API_KEY=your_key
```

--------------------------------

### Run Ultravox SpeechAgent Example

Source: https://github.com/telecmi/agents/blob/development/example/README.md

Executes the 'ultravox.py' example, which uses SpeechAgent with an all-in-one speech model. It leverages the Ultravox omni runtime and can optionally override TTS with Cartesia.

```bash
python ultravox/ultravox.py
```

--------------------------------

### AWS Polly TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Shows how to stream audio from AWS Polly TTS using the piopiy-ai library. Installation requires the 'aws' extra and setting the AWS_API_KEY environment variable. The example streams audio chunks asynchronously for a given text.

```bash
pip install "piopiy-ai[aws]"
export AWS_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.aws.tts import AWSPollyTTSService

async def main():
    tts = AWSPollyTTSService(api_key=os.getenv("AWS_API_KEY"))
    async for chunk in tts.stream("Hello from AWS"):
        pass

asyncio.run(main())
```

--------------------------------

### Install Piopiy with Groq and Set API Key

Source: https://github.com/telecmi/agents/blob/development/docs/llm/groq.md

Installs the piopiy library with Groq support and sets the GROQ_API_KEY environment variable. Ensure you replace 'your_key' with your actual Groq API key.

```bash
pip install "piopiy-ai[groq]"
export GROQ_API_KEY=your_key
```

--------------------------------

### Install piopiy with Together AI Support and Set API Key

Source: https://github.com/telecmi/agents/blob/development/docs/llm/together.md

This snippet shows how to install the piopiy library with the necessary dependencies for Together AI and how to set the required TOGETHER_API_KEY environment variable for authentication.

```bash
pip install "piopiy-ai[together]"
export TOGETHER_API_KEY=your_key
```

--------------------------------

### Groq TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Demonstrates streaming audio from Groq TTS with piopiy-ai. Install the 'groq' extra and set the GROQ_API_KEY environment variable. The code asynchronously streams audio chunks for specified text.

```bash
pip install "piopiy-ai[groq]"
export GROQ_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.groq.tts import GroqTTSService

async def main():
    tts = GroqTTSService(api_key=os.getenv("GROQ_API_KEY"))
    async for chunk in tts.stream("Hello from Groq"):
        pass

asyncio.run(main())
```

--------------------------------

### Install PIOPIY AI and Set Environment Variables

Source: https://context7.com/telecmi/agents/llms.txt

Installs the PIOPIY AI framework using pip. It supports installing with specific provider dependencies like 'cartesia', 'deepgram', 'openai', 'whisper', and 'silero'. It also shows how to set essential environment variables for API keys and agent authentication.

```bash
# Basic installation
pip install piopiy-ai

# Install with specific providers
pip install "piopiy-ai[cartesia,deepgram,openai]"

# Install for open-source stack
pip install "piopiy-ai[whisper,silero]"

# Install with interruption support
pip install "piopiy-ai[silero]"

# Set environment variables
export DEEPGRAM_API_KEY=your_deepgram_key
export OPENAI_API_KEY=your_openai_key
export CARTESIA_API_KEY=your_cartesia_key
export AGENT_ID=your_piopiy_agent_id
export AGENT_TOKEN=your_piopiy_agent_token
```

--------------------------------

### Install Sarvam TTS and Set API Key (Bash)

Source: https://github.com/telecmi/agents/blob/development/docs/tts/sarvam.md

Installs the piopiy-ai library with Sarvam support and sets the SARVAM_API_KEY environment variable. This is a prerequisite for using the Sarvam TTS service.

```bash
pip install "piopiy-ai[sarvam]"
export SARVAM_API_KEY=your_key
```

--------------------------------

### Install Piopiy with DeepSeek and Set API Key

Source: https://github.com/telecmi/agents/blob/development/docs/llm/deepseek.md

This snippet shows how to install the necessary Piopiy package with DeepSeek support and set the DEEPSEEK_API_KEY environment variable for authentication.

```bash
pip install "piopiy-ai[deepseek]"
export DEEPSEEK_API_KEY=your_key
```

--------------------------------

### Install piopiy with ElevenLabs and Set API Key

Source: https://github.com/telecmi/agents/blob/development/docs/tts/elevenlabs.md

Installs the piopiy library with ElevenLabs support and sets the ELEVENLABS_API_KEY environment variable. This is a prerequisite for using the ElevenLabs TTS service.

```bash
pip install "piopiy-ai[elevenlabs]"
export ELEVENLABS_API_KEY=your_key
```

--------------------------------

### Install LMNT TTS and Set API Key

Source: https://github.com/telecmi/agents/blob/development/docs/tts/lmnt.md

Installs the piopiy-ai library with LMNT support and sets the necessary LMNT API key as an environment variable. Ensure you replace 'your_key' with your actual API key.

```bash
pip install "piopiy-ai[lmnt]"
export LMNT_API_KEY=your_key
```

--------------------------------

### Install piopiy with Anthropic and Set API Key

Source: https://github.com/telecmi/agents/blob/development/docs/llm/anthropic.md

This snippet shows the necessary steps to install the piopiy library with Anthropic support and how to set the ANTHROPIC_API_KEY environment variable, which is required for authentication.

```bash
pip install "piopiy-ai[anthropic]"
export ANTHROPIC_API_KEY=your_key
```

--------------------------------

### Install piopiy with SambaNova support and set API key

Source: https://github.com/telecmi/agents/blob/development/docs/llm/sambanova.md

This snippet shows the necessary steps to install the piopiy library with SambaNova integration and to export the required SAMBANOVA_API_KEY environment variable for authentication.

```bash
pip install "piopiy-ai[sambanova]"
export SAMBANOVA_API_KEY=your_key
```

--------------------------------

### Install and Configure Perplexity LLM

Source: https://github.com/telecmi/agents/blob/development/docs/llm/perplexity.md

Installs the necessary piopiy package with Perplexity support and sets the Perplexity API key as an environment variable. Ensure you replace 'your_key' with your actual API key.

```bash
pip install "piopiy-ai[perplexity]"
export PERPLEXITY_API_KEY=your_key
```

--------------------------------

### Install and Use OpenAI TTS

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Installs the OpenAI integration for piopiy-ai and shows how to stream audio using an API key. Requires OPENAI_API_KEY environment variable. Outputs audio chunks.

```bash
pip install "piopiy-ai[openai]"
export OPENAI_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.openai.tts import OpenAITTSService

async def main():
    tts = OpenAITTSService(api_key=os.getenv("OPENAI_API_KEY"))
    async for chunk in tts.stream("Hello from OpenAI"):
        pass

asyncio.run(main())
```

--------------------------------

### Install XTTS TTS and Set API Key (Bash)

Source: https://github.com/telecmi/agents/blob/development/docs/tts/xtts.md

Installs the piopiy-ai library with XTTS support using pip and sets the XTTS API key as an environment variable. Ensure you replace 'your_key' with your actual API key.

```bash
pip install "piopiy-ai[xtts]"
export XTTS_API_KEY=your_key
```

--------------------------------

### Install Riva TTS and Set API Key (Bash)

Source: https://github.com/telecmi/agents/blob/development/docs/tts/riva.md

Installs the necessary piopiy-ai package with Riva support and sets the RIVA_API_KEY environment variable for authentication. Ensure you replace 'your_key' with your actual API key.

```bash
pip install "piopiy-ai[riva]"
export RIVA_API_KEY=your_key
```

--------------------------------

### Install piopiy with Nim support and set API key

Source: https://github.com/telecmi/agents/blob/development/docs/llm/nim.md

Installs the piopiy library with Nim LLM capabilities and sets the necessary API key as an environment variable. Ensure 'your_key' is replaced with your actual Nim API key.

```bash
pip install "piopiy-ai[nim]"
export NIM_API_KEY=your_key
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://github.com/telecmi/agents/blob/development/example/chatterbox/README.md

Demonstrates how to create and activate a Python virtual environment for isolating project dependencies. This is a recommended practice to avoid conflicts between different projects.

```bash
python3.11 -m venv chatterbox_env
source chatterbox_env/bin/activate   # On Windows: chatterbox_env\Scripts\activate
```

--------------------------------

### Install piopiy-ai with OpenAI and Set API Key

Source: https://github.com/telecmi/agents/blob/development/docs/llm/openai.md

Installs the necessary piopiy-ai package with OpenAI support and configures the OPENAI_API_KEY environment variable for authentication. Ensure you replace 'your_key' with your actual OpenAI API key.

```bash
pip install "piopiy-ai[openai]"
export OPENAI_API_KEY=your_key
```

--------------------------------

### QwenLLMService Initialization

Source: https://github.com/telecmi/agents/blob/development/docs/llm/qwen.md

Demonstrates how to initialize the QwenLLMService with essential parameters and optional configurations.

```APIDOC
## QwenLLMService Initialization

### Description
Initialize the `QwenLLMService` with your API key and desired model. You can also configure sampling parameters and optional service-level settings.

### Method
Python code snippet.

### Endpoint
N/A

### Parameters
#### Initialization Arguments
- **api_key** (string) - Required - Your Qwen API key.
- **model** (string) - Optional - The Qwen model to use. Defaults to `qwen-plus`.
- **params** (BaseOpenAILLMService.InputParams) - Optional - Parameters controlling sampling and output length.
- **base_url** (string) - Optional - Custom API endpoint for self-hosted proxies.
- **organization** (string) - Optional - Organization ID for multi-tenant setups.
- **project** (string) - Optional - Project ID for multi-tenant setups.
- **default_headers** (dict) - Optional - Additional headers to send with each request.
- **retry_timeout_secs** (int) - Optional - Request timeout in seconds.
- **retry_on_timeout** (bool) - Optional - Whether to retry once on timeout.

#### InputParams
- **temperature** (float) - Optional - Controls randomness. Higher values produce more random outputs. Defaults to 0.7.
- **top_p** (float) - Optional - Nucleus sampling. Alternative to `temperature`. Defaults to 0.9.
- **frequency_penalty** (float) - Optional - Discourages repeated tokens. Defaults to 0.5.
- **max_completion_tokens** (int) - Optional - Maximum length of the LLM's reply. Defaults to 256.
- **extra** (dict) - Optional - Dictionary for model-specific options.

### Request Example
```python
import os
from piopiy.services.qwen.llm import QwenLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={}
)

service = QwenLLMService(
    api_key=os.getenv("QWEN_API_KEY"),
    model="qwen-plus",
    params=params,
)
```

### Response
- **service** (QwenLLMService) - An initialized QwenLLMService instance.
```

--------------------------------

### Install and Configure piopiy-ai for Fireworks LLM

Source: https://github.com/telecmi/agents/blob/development/docs/llm/fireworks.md

Installs the piopiy-ai library with Fireworks support and sets the necessary API key as an environment variable. This is the initial setup required before using the Fireworks LLM service.

```bash
pip install "piopiy-ai[fireworks]"
export FIREWORKS_API_KEY=your_key
```

--------------------------------

### Quick Start: Create and Run a Voice Agent

Source: https://github.com/telecmi/agents/blob/development/README.md

This Python script demonstrates how to set up and run a basic voice agent using Piopiy AI. It initializes a VoiceAgent with custom instructions and a greeting, then configures Speech-to-Text (STT), Large Language Model (LLM), and Text-to-Speech (TTS) services. The agent connects to a backend service to handle calls.

```python
import asyncio
import os

from piopiy.agent import Agent
from piopiy.voice_agent import VoiceAgent
from piopiy.services.deepgram.stt import DeepgramSTTService
from piopiy.services.openai.llm import OpenAILLMService
from piopiy.services.cartesia.tts import CartesiaTTSService


async def create_session():
    voice_agent = VoiceAgent(
        instructions="You are an advanced voice AI.",
        greeting="Hello! How can I help you today?",
    )

    stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
    llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))
    tts = CartesiaTTSService(api_key=os.getenv("CARTESIA_API_KEY"))

    await voice_agent.Action(stt=stt, llm=llm, tts=tts)
    await voice_agent.start()


async def main():
    agent = Agent(
        agent_id=os.getenv("AGENT_ID"),
        agent_token=os.getenv("AGENT_TOKEN"),
        create_session=create_session,
    )
    await agent.connect()


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Inworld TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Shows how to stream audio from Inworld TTS using piopiy-ai. Requires installation of the 'inworld' extra and setting the INWORLD_API_KEY environment variable. The example streams audio chunks asynchronously.

```bash
pip install "piopiy-ai[inworld]"
export INWORLD_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.inworld.tts import InworldTTSService

async def main():
    tts = InworldTTSService(api_key=os.getenv("INWORLD_API_KEY"))
    async for chunk in tts.stream("Hello from Inworld"):
        pass

asyncio.run(main())
```

--------------------------------

### Initialize Qwen LLM Service (Python)

Source: https://github.com/telecmi/agents/blob/development/docs/llm/qwen.md

Demonstrates how to initialize the QwenLLMService in Python. It imports necessary classes, defines input parameters for controlling LLM generation (like temperature and max tokens), and instantiates the service using the API key from the environment and a specified model.

```python
import os
from piopiy.services.qwen.llm import QwenLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={},
)

service = QwenLLMService(
    api_key=os.getenv("QWEN_API_KEY"),
    model="qwen-plus",
    params=params,
)
```

--------------------------------

### Cartesia TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Provides an example of streaming audio from Cartesia TTS using piopiy-ai. Requires installation of the 'cartesia' extra and setting the CARTESIA_API_KEY environment variable. The function streams audio chunks asynchronously.

```bash
pip install "piopiy-ai[cartesia]"
export CARTESIA_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.cartesia.tts import CartesiaTTSService

async def main():
    tts = CartesiaTTSService(api_key=os.getenv("CARTESIA_API_KEY"))
    async for chunk in tts.stream("Hello from Cartesia"):
        pass

asyncio.run(main())
```

--------------------------------

### Initialize Groq TTS Service in Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/groq.md

Demonstrates how to initialize the GroqTTSService from the piopiy library. It shows how to pass the API key from environment variables and configure essential parameters like voice ID, model name, and output format.

```python
import os
from piopiy.services.groq.tts import GroqTTSService

tts = GroqTTSService(
    api_key=os.getenv("GROQ_API_KEY"),
    voice_id="Celeste-PlayAI",
    model_name="playai-tts",
    output_format="wav",
)
```

--------------------------------

### Cerebras LLM Service Setup and Usage

Source: https://github.com/telecmi/agents/blob/development/docs/llm/cerebras.md

This section details how to install the necessary libraries, set up your API key, and instantiate the CerebrasLLMService with input parameters.

```APIDOC
## Cerebras LLM Service Setup and Usage

### Description
This section covers the initial setup, including installation and API key configuration, followed by an example of how to instantiate the `CerebrasLLMService` with default or custom input parameters.

### Method
N/A (Setup and Initialization)

### Endpoint
N/A (Local Client Setup)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
pip install "piopiy-ai[cerebras]"
export CEREBRAS_API_KEY=your_key
```

```python
import os
from piopiy.services.cerebras.llm import CerebrasLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

# Define input parameters for the LLM
params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={}
)

# Initialize the CerebrasLLMService
service = CerebrasLLMService(
    api_key=os.getenv("CEREBRAS_API_KEY"),
    model="llama-3.3-70b",
    params=params,
)
```

### Response
#### Success Response (200)
N/A (Client-side initialization)

#### Response Example
N/A
```

--------------------------------

### Initialize TogetherLLMService in Python

Source: https://github.com/telecmi/agents/blob/development/docs/llm/together.md

Demonstrates how to initialize the TogetherLLMService in Python. It includes setting up input parameters like temperature and max tokens, and configuring the service with an API key and a specific Together AI model.

```python
import os
from piopiy.services.together.llm import TogetherLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={},
)

service = TogetherLLMService(
    api_key=os.getenv("TOGETHER_API_KEY"),
    model="meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo",
    params=params,
)
```

--------------------------------

### Neuphonic TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Demonstrates streaming audio from Neuphonic TTS with piopiy-ai. Install the 'neuphonic' extra and set the NEUPHONIC_API_KEY environment variable. The code asynchronously streams audio chunks for specified text.

```bash
pip install "piopiy-ai[neuphonic]"
export NEUPHONIC_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.neuphonic.tts import NeuphonicTTSService

async def main():
    tts = NeuphonicTTSService(api_key=os.getenv("NEUPHONIC_API_KEY"))
    async for chunk in tts.stream("Hello from Neuphonic"):
        pass

asyncio.run(main())
```

--------------------------------

### LMNT TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Illustrates streaming audio from LMNT TTS with piopiy-ai. Install the 'lmnt' extra and set the LMNT_API_KEY environment variable. The code asynchronously streams audio chunks for given text.

```bash
pip install "piopiy-ai[lmnt]"
export LMNT_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.lmnt.tts import LmntTTSService

async def main():
    tts = LmntTTSService(api_key=os.getenv("LMNT_API_KEY"))
    async for chunk in tts.stream("Hello from LMNT"):
        pass

asyncio.run(main())
```

--------------------------------

### Install Qwen LLM and Set API Key (Bash)

Source: https://github.com/telecmi/agents/blob/development/docs/llm/qwen.md

This snippet shows how to install the required piopiy package with Qwen support and set the QWEN_API_KEY environment variable. The API key is essential for authenticating with the Qwen API. Ensure you replace 'your_key' with your actual API key.

```bash
pip install "piopiy-ai[qwen]"
export QWEN_API_KEY=your_key
```

--------------------------------

### Deepgram TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Demonstrates streaming audio from Deepgram TTS with piopiy-ai. Install the 'deepgram' extra and set the DEEPGRAM_API_KEY environment variable. The code streams audio chunks asynchronously for specified text.

```bash
pip install "piopiy-ai[deepgram]"
export DEEPGRAM_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.deepgram.tts import DeepgramTTSService

async def main():
    tts = DeepgramTTSService(api_key=os.getenv("DEEPGRAM_API_KEY"))
    async for chunk in tts.stream("Hello from Deepgram"):
        pass

asyncio.run(main())
```

--------------------------------

### Initialize SambaNovaLLMService with parameters

Source: https://github.com/telecmi/agents/blob/development/docs/llm/sambanova.md

Demonstrates how to initialize the SambaNovaLLMService in Python. It includes setting up input parameters like temperature and max tokens using BaseOpenAILLMService.InputParams and authenticating with the API key from environment variables.

```python
import os
from piopiy.services.sambanova.llm import SambaNovaLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={},
)

service = SambaNovaLLMService(
    api_key=os.getenv("SAMBANOVA_API_KEY"),
    model="Llama-4-Maverick-17B-128E-Instruct",
    params=params,
)
```

--------------------------------

### Fish Audio TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Illustrates streaming audio from Fish Audio TTS with piopiy-ai. Install the 'fish' extra and set the FISH_API_KEY environment variable. The code asynchronously streams audio chunks for given text.

```bash
pip install "piopiy-ai[fish]"
export FISH_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.fish.tts import FishAudioTTSService

async def main():
    tts = FishAudioTTSService(api_key=os.getenv("FISH_API_KEY"))
    async for chunk in tts.stream("Hello from Fish"):
        pass

asyncio.run(main())
```

--------------------------------

### Initialize DeepSeek LLM Service in Python

Source: https://github.com/telecmi/agents/blob/development/docs/llm/deepseek.md

Demonstrates how to initialize the DeepSeekLLMService in Python using the Piopiy library. It includes setting up input parameters for controlling LLM generation like temperature and max tokens, and authenticating with an API key.

```python
import os
from piopiy.services.deepseek.llm import DeepSeekLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={},
)

service = DeepSeekLLMService(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    model="deepseek-chat",
    params=params,
)
```

--------------------------------

### Install piopiy with Ollama support and set API key

Source: https://github.com/telecmi/agents/blob/development/docs/llm/ollama.md

This snippet shows the necessary commands to install the piopiy library with Ollama integration and to set the required Ollama API key as an environment variable. Ensure you replace 'your_key' with your actual API key.

```bash
pip install "piopiy-ai[ollama]"
export OLLAMA_API_KEY=your_key
```

--------------------------------

### Azure TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Illustrates streaming audio from Azure TTS with the piopiy-ai library. Users need to install the 'azure' extra and set the AZURE_API_KEY environment variable. The code asynchronously streams audio chunks for provided text.

```bash
pip install "piopiy-ai[azure]"
export AZURE_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.azure.tts import AzureBaseTTSService

async def main():
    tts = AzureBaseTTSService(api_key=os.getenv("AZURE_API_KEY"))
    async for chunk in tts.stream("Hello from Azure"):
        pass

asyncio.run(main())
```

--------------------------------

### Initialize PlayHT TTS Service in Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/playht.md

Demonstrates how to initialize the PlayHTTTSService in Python. It shows setting the API key via environment variables and configuring essential parameters like user ID, voice engine, and sample rate. The `api_key` is retrieved from the environment, and other parameters like `user_id`, `voice_engine`, and `sample_rate` are explicitly set.

```python
import os
from piopiy.services.playht.tts import PlayHTTTSService

tts = PlayHTTTSService(
    api_key=os.getenv("PLAYHT_API_KEY"),
    user_id="USER_ID",
    voice_engine="Play3.0-mini",
    sample_rate=24000,
)
```

--------------------------------

### AsyncAI TTS Stream Example - Python

Source: https://github.com/telecmi/agents/blob/development/docs/tts/providers.md

Demonstrates how to stream audio from AsyncAI TTS using the piopiy-ai library. Requires installation of the 'asyncai' extra and setting the ASYNCAI_API_KEY environment variable. The function takes a text input and streams audio chunks asynchronously.

```bash
pip install "piopiy-ai[asyncai]"
export ASYNCAI_API_KEY=your_key
```

```python
import asyncio, os
from piopiy.services.asyncai.tts import AsyncAITTSService

async def main():
    tts = AsyncAITTSService(api_key=os.getenv("ASYNCAI_API_KEY"))
    async for chunk in tts.stream("Hello from AsyncAI"):
        pass

asyncio.run(main())
```

--------------------------------

### Initialize GroqLLMService with Parameters

Source: https://github.com/telecmi/agents/blob/development/docs/llm/groq.md

Initializes the GroqLLMService using the piopiy library. It configures input parameters like temperature and token limits, and sets the API key and model name for the service.

```python
import os
from piopiy.services.groq.llm import GroqLLMService
from piopiy.services.openai.base_llm import BaseOpenAILLMService

params = BaseOpenAILLMService.InputParams(
    temperature=0.7,
    top_p=0.9,
    frequency_penalty=0.5,
    max_completion_tokens=256,
    extra={},
)

service = GroqLLMService(
    api_key=os.getenv("GROQ_API_KEY"),
    model="llama-3.3-70b-versatile",
    params=params,
)
```