Vocode Core

repository·main·Indexed 25 days ago

https://github.com/vocodedev/vocode-core

An open-source voice SDK for building real-time voice-based LLM applications. Vocode provides abstractions to connect LLMs with transcription services (e.g., Deepgram, AssemblyAI), synthesis services (e.g., Azure, Eleven Labs), and telephony interfaces including phone calls, Zoom, and system audio. The library includes support for FastAPI-based backends, LangChain agents, and integrations with LiveKit and Telegram.

Tokens
50.6K
Snippets
147
Records
278
Agent score
86%

What's inside vocode

  1. Overview of Vocode core capabilities

    main

    Vocode is a framework designed for building voice-based LLM applications. It provides three core capabilities:

    1. Real-time Conversation Orchestration: Manages both streaming and turn-based interactions, including complex real-time tasks like endpointing and handling user interruptions.
    2. Provider Integrations: Offers built-in support for leading Speech-to-Text (STT), Text-to-Speech (TTS), and Large Language Model (LLM) providers, allowing for easy provider switching with minimal code changes.
    3. Cross-platform Support: Enables deployment across various platforms including web, telephone, and mobile, supporting use cases like making phone calls, building interactive websites, or joining Zoom meetings.
  2. Overview of Vocode capabilities

    main

    Vocode is an open-source library designed for building voice-based applications on top of Large Language Models (LLMs). It provides abstractions for conversation management, speech-to-text (STT), and text-to-speech (TTS) integrations.

    Key features include:

    • Conversation Abstractions: Support for both streaming and turn-based conversations.
    • Conversation Functionality: Features like endpointing and emotion tracking.
    • Integrations: Access to various STT and TTS providers.
    • Cross-platform Support: Capabilities for telephony, web, and Zoom applications.
  3. Understand the core components of a Vocode Conversation

    main

    A Vocode Conversation is composed of five core abstractions that handle the orchestration of voice-based LLM interactions. To build a conversation, you specify one of each of the following types:

    1. Transcriber: Handles speech recognition (converting audio to text).
    2. Agent: The AI/NLU layer (processing text and generating responses).
    3. Synthesizer: Handles speech synthesis (converting text to audio).
    4. Input Device: The source for audio input (e.g., a microphone).
    5. Output Device: The destination for audio output (e.g., a speaker).

    Vocode manages the asynchronous streaming of audio, response generation timing, and handling of interruptions and inaccuracies by orchestrating these components.

  4. Understand Vocode Agents

    main

    Vocode Agents are the core component of the Vocode API, acting as AI assistants that can be deployed to receive phone calls (by attaching them to Numbers) or used to make outbound calls via the calls/create endpoint.

    An agent is composed of several key elements:

    • Prompts: Instructions that control behavior.
    • Voices: The synthetic voice used by the agent.
    • Webhooks: Mechanisms to subscribe to agent events.
    • Conversational Dials: Controls for communication, such as interruption sensitivity.
    • Actions: Tools available to the agent (e.g., ending a conversation or transferring a call).
  5. Understand the ActionsWorker execution flow

    main

    The ActionsWorker (a specialized InterruptibleWorker) handles the asynchronous execution of actions. The lifecycle is as follows:

    1. Request: The Agent sends an action request to the ActionsWorker via an input queue.
    2. Creation: ActionsWorker uses an ActionFactory to create the action instance based on the request.
    3. Execution: The worker executes the action's run method.
    4. Output: The action returns an ActionOutput. The worker wraps this in an ActionResultAgentInput and places it in an output queue.
    5. Consumption: The Agent consumes the result from the output queue, adding it to the conversation transcript to influence future behavior.
  6. Supported languages for multilingual bots

    main

    Vocode bots default to English but can be configured to speak and understand other languages. This feature is currently in beta and works best when using ElevenLabs multilingual voices.

    Currently supported language codes:

    • en (English)
    • es (Spanish)
    • de (German)
  7. Quickstart: Spin up a conversation with system audio

    main

    You can create a real-time streaming conversation using your computer's microphone and speakers. This example uses DeepgramTranscriber for speech-to-text, ChatGPTAgent for the LLM logic, and AzureSynthesizer for text-to-speech.

    Note: You can overload settings like openai_api_key using a .env file.

    import asyncio
    import signal
    
    from pydantic_settings import BaseSettings, SettingsConfigDict
    
    from vocode.helpers import create_streaming_microphone_input_and_speaker_output
    from vocode.logging import configure_pretty_logging
    from vocode.streaming.agent.chat_gpt_agent import ChatGPTAgent
    from vocode.streaming.models.agent import ChatGPTAgentConfig
    from vocode.streaming.models.message import BaseMessage
    from vocode.streaming.models.synthesizer import AzureSynthesizerConfig
    from vocode.streaming.models.transcriber import (
        DeepgramTranscriberConfig,
        PunctuationEndpointingConfig,
    )
    from vocode.streaming.streaming_conversation import StreamingConversation
    from vocode.streaming.synthesizer.azure_synthesizer import AzureSynthesizer
    from vocode.streaming.transcriber.deepgram_transcriber import DeepgramTranscriber
    
    configure_pretty_logging()
    
    
    class Settings(BaseSettings):
        """
        Settings for the streaming conversation quickstart.
        These parameters can be configured with environment variables.
        """
    
        openai_api_key: str = "ENTER_YOUR_OPENAI_API_KEY_HERE"
        azure_speech_key: str = "ENTER_YOUR_AZURE_KEY_HERE"
        deepgram_api_key: str = "ENTER_YOUR_DEEPGRAM_API_KEY_HERE"
    
        azure_speech_region: str = "eastus"
    
        # This means a .env file can be used to overload these settings
        # ex: "OPENAI_API_KEY=my_key" will set openai_api_key over the default above
        model_config = SettingsConfigDict(
            env_file=".env",
            env_file_encoding="utf-8",
            extra="ignore",
        )
    
    
    settings = Settings()
    
    
    async def main():
        (
            microphone_input,
            speaker_output,
        ) = create_streaming_microphone_input_and_speaker_output(
            use_default_devices=False,
        )
    
        conversation = StreamingConversation(
            output_device=speaker_output,
            transcriber=DeepgramTranscriber(
                DeepgramTranscriberConfig.from_input_device(
                    microphone_input,
                    endpointing_config=PunctuationEndpointingConfig(),
                    api_key=settings.deepgram_api_key,
                ),
            ),
            agent=ChatGPTAgent(
                ChatGPTAgentConfig(
                    openai_api_key=settings.openai_api_key,
                    initial_message=BaseMessage(text="What up"),
                    prompt_preamble="""The AI is having a pleasant conversation about life""
                )
            ),
            synthesizer=AzureSynthesizer(
                AzureSynthesizerConfig.from_output_device(speaker_output),
                azure_speech_key=settings.azure_speech_key,
                azure_speech_region=settings.azure_speech_region,
            ),
        )
        await conversation.start()
        print("Conversation started, press Ctrl+C to end")
        signal.signal(signal.SIGINT, lambda _0, _1: asyncio.create_task(conversation.terminate()))
        while conversation.is_active():
            chunk = await microphone_input.get_audio()
            conversation.receive_audio(chunk)
    
    
    if __name__ == "__main__":
        asyncio.run(main())
  8. Run Do Not Call detection on outbound calls

    main

    You can configure whether Vocode performs automatic rudimentary Do Not Call analysis on outbound calls by using the run_do_not_call_detection parameter during call creation.

    By default, this is set to False. If you enable it, the result of the analysis (indicating if the receiving party requested to be on a Do Not Call list) will be populated in the do_not_call_result field of the Call object returned by the get_call endpoint after the call is completed.

    from vocode import CreateCallAgentParams, PromptParams
    
    vocode_client.calls.create_call(
        from_number="<YOUR VOCODE NUMBER>",
        to_number="15555555555",
        agent=CreateCallAgentParams(
            prompt=PromptParams(
                content="Ask Eliot if the sun is on today"
            ),
        ),
        run_do_not_call_detection=True
    )