Pipecat

pipecat-sprag is Sprag's plugin for Pipecat, a framework for building voice-enabled, real-time, multimodal AI applications. It adds a speech-to-text, an LLM, and a text-to-speech service, each of which takes the place of any other Pipecat service of its kind.

Installation

uv add pipecat-sprag

Then set your Sprag API key as an environment variable:

export SPRAG_API_KEY=<your_sprag_api_key>

Generate a key from API keys in the Sprag app. See the quickstart if you do not have an account yet.

Configuration

Each service reads SPRAG_API_KEY from the environment, or takes the key as api_key=. Its model and other options are passed as settings=<Service>.Settings(...).

from pipecat_sprag.llm import SpragLLMService
from pipecat_sprag.stt import SpragSTTService
from pipecat_sprag.tts import SpragTTSService

stt = SpragSTTService()
llm = SpragLLMService(
    settings=SpragLLMService.Settings(
        system_instruction="You are a helpful assistant in a voice conversation.",
    ),
)
tts = SpragTTSService(settings=SpragTTSService.Settings(voice="marin"))

Pipeline

A Pipecat voice pipeline captures the user's audio, transcribes it, generates a reply, speaks the reply, and plays the audio back. The three services take the transcribe, generate, and speak positions:

pipeline = Pipeline([
    transport.input(),
    stt,
    user_aggregator,
    llm,
    tts,
    transport.output(),
    assistant_aggregator,
])

examples/voice_agent.py in the plugin repository is a complete voice agent built this way.

Services

Speech to text. SpragSTTService streams the user's audio over a WebSocket and emits each turn's transcript.

Text to speech. SpragTTSService speaks the reply over a WebSocket, one sentence at a time.

LLM. SpragLLMService generates the reply through POST /v1/chat/completions, with function calling and token usage metrics. The same page covers OpenAIRealtimeLLMService, which replaces the transcribe, generate, and speak stages with one WebSocket.

Pipecat's OpenAI services

Pipecat's own OpenAI services also run against Sprag. Pass base_url and api_key to the service constructor and name a Sprag model. They are constructor arguments on every service, not fields of its Settings.

Each service page ends with a section on the OpenAI service for its stage.

Choosing between them

Use separate transcription, LLM, and synthesis stages when you want to pick the reasoning model independently of the transcription and synthesis models. Use OpenAIRealtimeLLMService to collapse those three stages into one hop while keeping Pipecat's transports, Frame types, and event handlers. Use the realtime API directly when you are not building on Pipecat at all.