bolna-ai/bolna

Bol na – Open‑source Voice‑AI Orchestration Platform

What it is – Bol na is a production‑ready framework that lets you build voice‑first conversational assistants powered by large language models (LLMs). It wires together speech‑to‑text (ASR), an LLM, and text‑to‑speech (TTS) providers, and can place and receive phone calls through telephony services. All of the orchestration logic lives in this repository; the hosted API and UI that Bol na offers are built on top of it.

---

Core concepts

Component	Role	Example providers
Telephony	Initiates/receives phone calls and streams audio over websockets	Twilio, Plivo (others can be added)
ASR (Transcriber)	Turns incoming audio into text	Deepgram, Azure
LLM Agent	Generates the conversational response	OpenAI, DeepSeek, Llama, Cohere, Mistral (via LiteLLM)
TTS (Synthesizer)	Converts LLM output back to spoken audio	AWS Polly, ElevenLabs, OpenAI, Cartesia, etc.
Redis	Persists agent state and prompt data
ngrok	Exposes the local server to the public internet for telephony callbacks

---

Key features

• End‑to‑end orchestration – One Python‑level pipeline (Assistant) that streams audio → text → LLM → audio.
• Provider‑agnostic – Plug‑in any supported ASR, LLM, or TTS service via environment variables; the code uses the liteLLM wrapper for LLMs.
• Telephony integration – Ready‑made Docker containers for Twilio and Plivo, with a clear path to add others (Vonage, Telnyx, etc.).
• Streaming – Both transcription and synthesis can be streamed, enabling low‑latency voice interactions.
• Self‑hosted – All components run in Docker Compose (Bol na server, telephony server, Redis, ngrok), so you keep data and keys in‑house.
• Extensible – Adding a new telephony or TTS provider only requires implementing a handler class and a small server wrapper.

---

Typical workflow (Python API)

from bolna.assistant import Assistant
from bolna.models import (
    Transcriber, Synthesizer, ElevenLabsConfig,
    LlmAgent, SimpleLlmAgent,
)

assistant = Assistant(name="demo_agent")

# 1️⃣ Speech‑to‑text
transcriber = Transcriber(provider="deepgram", model="nova-2", stream=True)

# 2️⃣ LLM response
llm = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="openai",
        model="gpt-4o-mini",
        temperature=0.3,
    ),
)

# 3️⃣ Text‑to‑speech
synth = Synthesizer(
    provider="elevenlabs",
    provider_config=ElevenLabsConfig(voice="George", voice_id="JBFqnCBsd6RMkjVDRZzb"),
    stream=True,
    audio_format="wav",
)

assistant.add_task(
    task_type="conversation",
    llm_agent=llm,
    transcriber=transcriber,
    synthesizer=synth,
    enable_textual_input=False,
)

# Run – yields incremental result dicts
async for chunk in assistant.execute():
    print(chunk)

The same Assistant can be used in a text‑only mode by omitting the transcriber/synthesizer and setting enable_textual_input=True.

---

Getting started locally

1. Clone the repo and copy .env.sample → .env, filling in API keys for the providers you plan to use (OpenAI, Deepgram, ElevenLabs, Twilio, etc.).
2. Docker‑compose – The local_setup/ folder contains a docker-compose.yml that builds four containers:
   • bolna-app – the core orchestration server
   • twilio-app or plivo-app – telephony webhook server
   • ngrok – exposes the webhook URL publicly
   • redis – state store
3. Start everything with the helper script:

   cd local_setup
   chmod +x start.sh
   ./start.sh   # builds with BuildKit and runs in detached mode
   

4. Create an agent via the REST API (API.md) or directly with the Python SDK as shown above.
5. Make a call – the telephony server will receive the webhook from Twilio/Plivo, forward audio to Bol na, and stream the synthesized reply back to the caller.

---

Extending the platform

• Add a new telephony provider – implement an input handler in bolna/input_handlers/telephony_providers/ and an output handler in bolna/output_handlers/telephony_providers/, then write a small server similar to twilio_api_server.py.
• Add a new ASR/TTS provider – expose the required credentials in .env and add the provider to the mapping in bolna/providers.py.
• Custom LLM logic – plug a different LlmAgent subclass or modify the prompt flow; the framework treats the LLM as a black‑box callable.

---

Community & support

• Discord – active chat channel for help and feature discussion.
• Docs – hosted at https://docs.bolna.ai (API reference, provider deep‑dives, deployment guides).
• Contributing – MIT‑licensed, PRs are welcome; the repo includes a CONTRIBUTING.md and a list of open issues.

---

License

MIT – you can use, modify, and redistribute the code freely.