docs.VoiceRun

Basic Usage

Simple Chat Completion#

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="kore"
        )

    if isinstance(event, TextEvent):
        user_message = event.data.get("text", "N/A")
        
        # Using dictionary format
        response = await generate_chat_completion({
            "provider": "anthropic",
            "api_key": context.variables.get("ANTHROPIC_API_KEY"),
            "model": "claude-haiku-4-5",
            "messages": [
                {"role": "user", "content": user_message}
            ]
        })
        
        if response.message.content:
            yield TextToSpeechEvent(
                text=response.message.content,
                voice="kore"
            )

Using Object Format#

from primfunctions.events import Event, StartEvent, TextEvent, TextToSpeechEvent
from primfunctions.context import Context
from voicerun_completions import (
    generate_chat_completion,
    ChatCompletionRequest,
    CompletionsProvider,
    UserMessage,
)

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        yield TextToSpeechEvent(
            text="Hello! I'm ready to answer your questions.",
            voice="kore"
        )

    if isinstance(event, TextEvent):
        user_message = event.data.get("text", "N/A")
        
        # Using object format for better type safety
        request = ChatCompletionRequest(
            provider=CompletionsProvider.ANTHROPIC,
            api_key=context.variables.get("ANTHROPIC_API_KEY"),
            model="claude-haiku-4-5",
            messages=[
                UserMessage(content=user_message)
            ]
        )
        
        response = await generate_chat_completion(request)
        if response.message.content:
            yield TextToSpeechEvent(
                text=response.message.content,
                voice="kore"
            )

Multi-Turn Conversations#

from primfunctions.events import Event, StartEvent, TextEvent, TextToSpeechEvent
from primfunctions.context import Context
from voicerun_completions import (
    generate_chat_completion,
    ConversationHistory,
    UserMessage,
    deserialize_conversation,
)

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        yield TextToSpeechEvent(
            text="Hello! I can remember our conversation.",
            voice="kore"
        )

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

        # Deserialize conversation history from context
        messages: ConversationHistory = deserialize_conversation(context.get_completion_messages())
        messages.append(UserMessage(content=user_message))

        response = await generate_chat_completion({
            "provider": "anthropic",
            "api_key": context.variables.get("ANTHROPIC_API_KEY"),
            "model": "claude-haiku-4-5",
            "messages": messages
        })

        # Store updated conversation history
        messages.append(response.message)
        context.set_completion_messages(messages)

        if response.message.content:
            yield TextToSpeechEvent(
                text=response.message.content,
                voice="kore"
            )

Context Completion Methods#

The Context object provides three utility methods for managing conversation history with voicerun_completions:

get_completion_messages()#

Returns the conversation history as a list of dictionaries. Use deserialize_conversation() to convert to typed message objects.

from voicerun_completions import deserialize_conversation

# Get messages as list of dicts
raw_messages = context.get_completion_messages()

# Convert to typed ConversationHistory for manipulation
messages = deserialize_conversation(context.get_completion_messages())

add_completion_message(message)#

Adds a single message to the conversation history. Accepts either a typed message object or a dictionary.

from voicerun_completions import UserMessage, AssistantMessage

# Add typed message objects
context.add_completion_message(UserMessage(content="Hello"))
context.add_completion_message(response.message)

# Or add dictionaries directly
context.add_completion_message({"role": "user", "content": "Hello"})

set_completion_messages(messages)#

Replaces the entire conversation history. Accepts a list of typed message objects or dictionaries.

from voicerun_completions import ConversationHistory, UserMessage, deserialize_conversation

# Get current history as typed objects
messages: ConversationHistory = deserialize_conversation(context.get_completion_messages())

# Modify the history
messages.append(UserMessage(content=user_message))
messages.append(response.message)

# Save back to context
context.set_completion_messages(messages)

Typical Usage Pattern#

Setting completion messages at the end of the turn rather than calling add_completion_message throughout can help prevent potential malformed completion messages history issues in the event of interruptions.

# 1. Get and deserialize existing messages
messages = deserialize_conversation(context.get_completion_messages())

# 2. Add the new user message
messages.append(UserMessage(content=user_message))

# 3. Call the completion API
response = await generate_chat_completion({...})

# 4. Add the assistant response
messages.append(response.message)

# 5. Save back to context
context.set_completion_messages(messages)

System Messages#

from primfunctions.events import Event, StartEvent, TextEvent, TextToSpeechEvent
from primfunctions.context import Context
from voicerun_completions import generate_chat_completion, SystemMessage, UserMessage

async def handler(event: Event, context: Context):
    if isinstance(event, StartEvent):
        yield TextToSpeechEvent(
            text="Ahoy! I be a helpful assistant that speaks like a pirate.",
            voice="kore"
        )

    if isinstance(event, TextEvent):
        user_message = event.data.get("text", "N/A")
        
        response = await generate_chat_completion({
            "provider": "anthropic",
            "api_key": context.variables.get("ANTHROPIC_API_KEY"),
            "model": "claude-haiku-4-5",
            "messages": [
                SystemMessage(content="You are a helpful assistant that speaks like a pirate."),
                UserMessage(content=user_message)
            ]
        })
        
        if response.message.content:
            yield TextToSpeechEvent(
                text=response.message.content,
                voice="kore"
            )

Request Parameters#

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="I can tell you stories with different styles.",
            voice="kore"
        )

    if isinstance(event, TextEvent):
        user_message = event.data.get("text", "N/A")
        
        response = await generate_chat_completion({
            "provider": "anthropic",
            "api_key": context.variables.get("ANTHROPIC_API_KEY"),
            "model": "claude-haiku-4-5",
            "messages": [{"role": "user", "content": user_message}],
            "temperature": 0.7,        # Control randomness (0.0-1.0)
            "max_tokens": 500,         # Maximum response length
            "timeout": 30.0,           # Request timeout in seconds
        })
        
        if response.message.content:
            yield TextToSpeechEvent(
                text=response.message.content,
                voice="kore"
            )

Next Steps#

chatcompletiongetting-started