Metadata-Version: 2.4
Name: voicerun_completions
Version: 0.4.0
Summary: VoiceRun Completions
Author: VoiceRun
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: loguru
Requires-Dist: openai==2.20.0
Requires-Dist: anthropic==0.84.0
Requires-Dist: google-genai==1.63.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"

# 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"
            )
```

## Connection Reuse with `CompletionsClient`

Use `CompletionsClient` to reuse HTTP connections across requests. This avoids the TLS handshake overhead of creating a new SDK client on every call — important for voice agents where latency matters.

### In a VoiceRun Agent

Create the client at module level so it persists across handler invocations. The agent handler is called per-event, but the module-level client lives for the lifetime of the process, keeping connections warm.

```python
from primfunctions.events import Event, StartEvent, TextEvent, TextToSpeechEvent
from primfunctions.context import Context
from voicerun_completions import CompletionsClient, deserialize_conversation, UserMessage

# Module-level client — connections are reused across all handler calls
completions = CompletionsClient()

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        yield TextToSpeechEvent(text="Hello! Ask me anything.", voice="nova")

    if isinstance(event, TextEvent):
        user_message = event.data.get("text", "N/A")

        messages = deserialize_conversation(context.get_completion_messages())
        messages.append(UserMessage(content=user_message))

        stream = await completions.generate_chat_completion_stream(
            request={
                "provider": "anthropic",
                "api_key": context.variables.get("ANTHROPIC_API_KEY"),
                "model": "claude-haiku-4-5",
                "messages": messages,
            },
            stream_options={"stream_sentences": True, "clean_sentences": True},
        )

        async for chunk in stream:
            if chunk.type == "content_sentence":
                yield TextToSpeechEvent(text=chunk.sentence, voice="nova")
            elif chunk.type == "response":
                messages.append(chunk.response.message)
                context.set_completion_messages(messages)
```

### In Other Applications

For servers or scripts where you control the lifecycle, you can also use the context manager:

```python
from voicerun_completions import CompletionsClient

async with CompletionsClient() as client:
    response = await client.generate_chat_completion({...})
    stream = await client.generate_chat_completion_stream({...})
# All SDK connections closed automatically
```

The module-level `generate_chat_completion()` and `generate_chat_completion_stream()` functions still work as before without connection reuse.

## 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

## Git Worktrees (Parallel Agent Development)

This repo supports running multiple coding agents in parallel using git worktrees. Each agent gets an isolated working directory with its own branch while sharing the same git object store.

Worktrees are stored in `.worktrees/` (gitignored).

### Create a worktree

```bash
git worktree add .worktrees/feature-xyz -b feature-xyz
```

### List active worktrees

```bash
git worktree list
```

### Remove a worktree

```bash
git worktree remove .worktrees/feature-xyz
```

### Clean up stale worktrees

```bash
git worktree prune
```
