voicerun_completions 0.3.3
VoiceRun Completions
Requires Python: >=3.12

# voicerun_completions

A comprehensive, unified SDK for interacting with multiple LLM providers (OpenAI, Anthropic, Google, and Vertex Anthropic) through a single, consistent API. This library simplifies working with different providers by normalizing their APIs and providing powerful features like automatic fallbacks, retry logic, and advanced streaming options.

## Quick Start

```python
from primfunctions.events import Event, StartEvent, TextEvent, TextToSpeechEvent
from primfunctions.context import Context
from voicerun_completions import generate_chat_completion

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        yield TextToSpeechEvent(
            text="Hello! Ask me anything and I'll answer your question.",
            voice="nova"
        )

    if isinstance(event, TextEvent):
        user_message = event.data.get("text", "")
        
        response = await generate_chat_completion({
            "provider": "openai",
            "api_key": context.variables.get("OPENAI_API_KEY"),
            "model": "gpt-5-mini",
            "messages": [
                {"role": "user", "content": user_message}
            ]
        })
        
        if response.message.content:
            yield TextToSpeechEvent(
                text=response.message.content,
                voice="nova"
            )
```

## Documentation

- [Installation](docs/installation.md) - Installation instructions and prerequisites
- [Core Concepts](docs/core-concepts.md) - Providers, message types, and request formats
- [Basic Usage](docs/basic-usage.md) - Getting started with chat completions
- [Streaming](docs/streaming.md) - Token and sentence-based streaming
- [Tool/Function Calling](docs/tool-calling.md) - Using tools and function calling
- [Reliability: Retries & Fallbacks](docs/reliability.md) - Retry logic and automatic fallbacks
- [Advanced Features](docs/advanced-features.md) - Cache breakpoints, vendor-specific options, and more
- [API Reference](docs/api-reference.md) - Complete API documentation
- [Examples](docs/examples.md) - Complete working examples
- [Best Practices](docs/best-practices.md) - Best practices and error handling

## Testing

Install dev dependencies:

```bash
uv pip install -e ".[dev]"
```

Run unit tests (no API keys required):

```bash
uv run pytest -m "not integration" -v
```

Run all tests including integration (requires API keys in environment):

```bash
uv run pytest -v
```

Run a specific test file:

```bash
uv run pytest tests/test_google_schema_sanitization.py -v
```

Integration tests require one or more of these environment variables:

- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`
- `GEMINI_API_KEY`
- `GCP_SERVICE_ACCOUNT_JSON` / `GCP_PROJECT_ID` (for Vertex tests)

Tests missing the required key will be skipped automatically.

## Features

- **Unified API** - Single interface for OpenAI, Anthropic, Google, and Vertex Anthropic
- **Automatic Fallbacks** - Seamlessly fallback to alternative providers on failure
- **Retry Logic** - Built-in exponential backoff retry mechanism
- **Advanced Streaming** - Token-based and sentence-based streaming for real-time applications
- **Tool Calling** - Unified tool/function calling across all providers
- **Type Safety** - Full type hints and support for both dict and object formats