# bolna-ai/bolna architecture

> Architecture diagram of the GitHub repository bolna-ai/bolna, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bolna-ai/bolna
- Repository: https://github.com/bolna-ai/bolna

## Overview

#### Purpose and Entry Points
Bolna is an asynchronous Python orchestration framework for streaming voice and text conversational agents. The public programmatic entry point is `bolna/assistant.py`, where `Assistant` is configured with tasks and consumed through the async-generator `execute()` API. Configuration/data models live in `bolna/models.py`; runnable examples are `examples/simple_assistant.py` and `examples/text_only_assistant.py`.

#### Task and Conversation Orchestration
`Assistant` delegates task lifecycle and per-turn coordination to manager-layer components. `bolna/agent_manager/task_manager.py` organizes configured tasks, while `bolna/agent_manager/assistant_manager.py` manages assistant-level execution. `bolna/agent_manager/interruption_manager.py` is a core control boundary for barge-in/interruption behavior, and `bolna/agent_manager/voicemail_handler.py` supports call-specific terminal handling.

#### Agent Execution Models
Agent types define what happens after input reaches the conversational core. `bolna/agent_types/base_agent.py` establishes the shared agent contract; `bolna/agent_types/contextual_conversational_agent.py` implements context-aware conversational behavior. Graph-driven workflows are represented by `bolna/agent_types/graph_agent.py` and `bolna/agent_types/graph_based_conversational_agent.py`, enabling routing/control-flow beyond a linear ASR→LLM→TTS turn. Specialized stages include extraction, knowledge-base, summarization, and webhook agents.

#### Streaming Media Pipeline
The primary voice path is bidirectional streaming: input audio → transcription → agent/LLM → synthesis → output audio. ASR provider implementations conform to the transcriber abstraction in `bolna/transcriber/base_transcriber.py` and are selected/managed through `bolna/transcriber/transcriber_pool.py`. TTS follows the equivalent abstraction and pooling boundary in `bolna/synthesizer/base_synthesizer.py` and `bolna/synthesizer/synthesizer_pool.py`. This design allows provider/model switching without coupling orchestration to a specific speech vendor.

#### LLM and Tool Boundary
LLM requests and streaming responses are abstracted in `bolna/llms/llm.py`, with LiteLLM-backed multi-provider support in `bolna/llms/litellm.py` and OpenAI-specific handling in `bolna/llms/openai_llm.py`. Message schemas and tool-call accumulation are isolated in `bolna/llms/message_models.py` and `bolna/llms/tool_call_accumulator.py`. Function/tool invocation support is coordinated through `bolna/helpers/function_calling_helpers.py`, separating model output from application-side execution.

#### Transport and Telephony Adapters
Input and output handler layers isolate runtime transport from the agent pipeline. Generic paths are `bolna/input_handlers/default.py` and `bolna/output_handlers/default.py`; telephony paths are `bolna/input_handlers/telephony.py` and `bolna/output_handlers/telephony.py`. Provider adapters, such as `bolna/input_handlers/telephony_providers/twilio.py` and `bolna/output_handlers/telephony_providers/twilio.py`, translate vendor WebSocket events/audio formats at the system boundary.

#### State, Deployment, and External Services
Conversation state and event metadata are handled by `bolna/helpers/conversation_history.py` and `bolna/helpers/mark_event_meta_data.py`; cache abstractions begin at `bolna/memory/cache/base_cache.py`. The local deployment is Docker Compose-based in `local_setup/docker-compose.yml`, running Bolna, a Twilio/Plivo telephony server, ngrok, and Redis. External dependencies include telephony providers, ASR/TTS vendors, LLM APIs or self-hosted VLLM endpoints, and optional RAG services via `bolna/helpers/rag_service_client.py`.

Main entry points: [`bolna/agent_types/contextual_conversational_agent.py`](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_types/contextual_conversational_agent.py) (Contextual conversational agent), [`bolna/agent_manager/assistant_manager.py`](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/assistant_manager.py) (Assistant manager), [`bolna/agent_types/base_agent.py`](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_types/base_agent.py) (Base agent), [`bolna/transcriber/transcriber_pool.py`](https://github.com/bolna-ai/bolna/blob/master/bolna/transcriber/transcriber_pool.py) (Transcriber pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_assistant["Assistant<br/>async entry point<br/>[assistant.py]"]
  node_models["Configuration models<br/>data models<br/>[models.py]"]
end

subgraph group_orchestration["Orchestration"]
  node_assistant_manager["Assistant manager<br/>execution coordinator"]
  node_task_manager["Task manager<br/>task lifecycle<br/>[task_manager.py]"]
  node_interruptions["Interruption manager<br/>barge-in control"]
  node_voicemail["Voicemail handler<br/>call terminal handler"]
end

subgraph group_agents["Agent execution"]
  node_base_agent["Base agent<br/>agent contract<br/>[base_agent.py]"]
  node_conversational_agent["Contextual conversational agent<br/>conversation agent"]
  node_graph_agents["Graph workflow agents<br/>graph control flow"]
  node_llm["LLM abstraction<br/>streaming LLM<br/>[llm.py]"]
  node_function_calls["Function calling<br/>tool invocation"]
end

subgraph group_media["Streaming media"]
  node_transcriber_pool["Transcriber pool<br/>ASR provider selection"]
  node_base_transcriber["Base transcriber<br/>ASR contract"]
  node_synthesizer_pool["Synthesizer pool<br/>TTS provider selection"]
  node_base_synthesizer["Base synthesizer<br/>TTS contract"]
end

subgraph group_adapters["Transport adapters"]
  node_input_transport["Input handlers<br/>transport ingress<br/>[default.py]"]
  node_telephony_input["Twilio input adapter<br/>telephony ingress<br/>[twilio.py]"]
  node_output_transport["Output handlers<br/>transport egress<br/>[default.py]"]
  node_telephony_output["Twilio output adapter<br/>telephony egress<br/>[twilio.py]"]
end

subgraph group_services["State & external services"]
  node_history[("Conversation history<br/>conversation state")]
  node_cache[("Cache abstraction<br/>memory contract<br/>[base_cache.py]")]
  node_rag["RAG service client<br/>knowledge service"]
end

node_models -->|"configures"| node_assistant
node_assistant -->|"delegates execution"| node_assistant_manager
node_assistant_manager -->|"coordinates tasks"| node_task_manager
node_task_manager -->|"instantiates"| node_base_agent
node_base_agent -->|"implemented by"| node_conversational_agent
node_base_agent -->|"implemented by"| node_graph_agents
node_input_transport -->|"audio input"| node_transcriber_pool
node_telephony_input -->|"vendor events"| node_input_transport
node_transcriber_pool -->|"selects provider"| node_base_transcriber
node_transcriber_pool -->|"transcript"| node_conversational_agent
node_conversational_agent -->|"streams prompts"| node_llm
node_graph_agents -->|"uses"| node_llm
node_llm -->|"tool calls"| node_function_calls
node_function_calls -.->|"tool results"| node_conversational_agent
node_conversational_agent -->|"response text"| node_synthesizer_pool
node_synthesizer_pool -->|"selects provider"| node_base_synthesizer
node_synthesizer_pool -->|"synthesized audio"| node_output_transport
node_output_transport -->|"telephony audio"| node_telephony_output
node_assistant_manager -->|"handles barge-in"| node_interruptions
node_assistant_manager -->|"handles terminal calls"| node_voicemail
node_conversational_agent -->|"reads and updates"| node_history
node_conversational_agent -.->|"uses"| node_cache
node_conversational_agent -.->|"retrieves knowledge"| node_rag

click node_assistant "https://github.com/bolna-ai/bolna/blob/master/bolna/assistant.py"
click node_models "https://github.com/bolna-ai/bolna/blob/master/bolna/models.py"
click node_assistant_manager "https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/assistant_manager.py"
click node_task_manager "https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/task_manager.py"
click node_interruptions "https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/interruption_manager.py"
click node_voicemail "https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/voicemail_handler.py"
click node_base_agent "https://github.com/bolna-ai/bolna/blob/master/bolna/agent_types/base_agent.py"
click node_conversational_agent "https://github.com/bolna-ai/bolna/blob/master/bolna/agent_types/contextual_conversational_agent.py"
click node_graph_agents "https://github.com/bolna-ai/bolna/blob/master/bolna/agent_types/graph_based_conversational_agent.py"
click node_transcriber_pool "https://github.com/bolna-ai/bolna/blob/master/bolna/transcriber/transcriber_pool.py"
click node_base_transcriber "https://github.com/bolna-ai/bolna/blob/master/bolna/transcriber/base_transcriber.py"
click node_synthesizer_pool "https://github.com/bolna-ai/bolna/blob/master/bolna/synthesizer/synthesizer_pool.py"
click node_base_synthesizer "https://github.com/bolna-ai/bolna/blob/master/bolna/synthesizer/base_synthesizer.py"
click node_llm "https://github.com/bolna-ai/bolna/blob/master/bolna/llms/llm.py"
click node_function_calls "https://github.com/bolna-ai/bolna/blob/master/bolna/helpers/function_calling_helpers.py"
click node_input_transport "https://github.com/bolna-ai/bolna/blob/master/bolna/input_handlers/default.py"
click node_telephony_input "https://github.com/bolna-ai/bolna/blob/master/bolna/input_handlers/telephony_providers/twilio.py"
click node_output_transport "https://github.com/bolna-ai/bolna/blob/master/bolna/output_handlers/default.py"
click node_telephony_output "https://github.com/bolna-ai/bolna/blob/master/bolna/output_handlers/telephony_providers/twilio.py"
click node_history "https://github.com/bolna-ai/bolna/blob/master/bolna/helpers/conversation_history.py"
click node_cache "https://github.com/bolna-ai/bolna/blob/master/bolna/memory/cache/base_cache.py"
click node_rag "https://github.com/bolna-ai/bolna/blob/master/bolna/helpers/rag_service_client.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_assistant,node_models toneBlue
class node_assistant_manager,node_task_manager,node_interruptions,node_voicemail toneAmber
class node_base_agent,node_conversational_agent,node_graph_agents,node_llm,node_function_calls toneMint
class node_transcriber_pool,node_base_transcriber,node_synthesizer_pool,node_base_synthesizer toneRose
class node_input_transport,node_telephony_input,node_output_transport,node_telephony_output toneIndigo
class node_history,node_cache,node_rag toneTeal
```

## Components

### Public API

- [Assistant](https://github.com/bolna-ai/bolna/blob/master/bolna/assistant.py): async entry point · Configures tasks and streams execute() results. · `bolna/assistant.py`
- [Configuration models](https://github.com/bolna-ai/bolna/blob/master/bolna/models.py): data models · `bolna/models.py`

### Orchestration

- [Assistant manager](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/assistant_manager.py): execution coordinator · `bolna/agent_manager/assistant_manager.py`
- [Task manager](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/task_manager.py): task lifecycle · `bolna/agent_manager/task_manager.py`
- [Interruption manager](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/interruption_manager.py): barge-in control · `bolna/agent_manager/interruption_manager.py`
- [Voicemail handler](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_manager/voicemail_handler.py): call terminal handler · `bolna/agent_manager/voicemail_handler.py`

### Agent execution

- [Base agent](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_types/base_agent.py): agent contract · `bolna/agent_types/base_agent.py`
- [Contextual conversational agent](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_types/contextual_conversational_agent.py): conversation agent · `bolna/agent_types/contextual_conversational_agent.py`
- [Graph workflow agents](https://github.com/bolna-ai/bolna/blob/master/bolna/agent_types/graph_based_conversational_agent.py): graph control flow · Supports non-linear conversational routing. · `bolna/agent_types/graph_based_conversational_agent.py`
- [LLM abstraction](https://github.com/bolna-ai/bolna/blob/master/bolna/llms/llm.py): streaming LLM · `bolna/llms/llm.py`
- [Function calling](https://github.com/bolna-ai/bolna/blob/master/bolna/helpers/function_calling_helpers.py): tool invocation · Executes application-side tools from model output. · `bolna/helpers/function_calling_helpers.py`

### Streaming media

- [Transcriber pool](https://github.com/bolna-ai/bolna/blob/master/bolna/transcriber/transcriber_pool.py): ASR provider selection · `bolna/transcriber/transcriber_pool.py`
- [Base transcriber](https://github.com/bolna-ai/bolna/blob/master/bolna/transcriber/base_transcriber.py): ASR contract · `bolna/transcriber/base_transcriber.py`
- [Synthesizer pool](https://github.com/bolna-ai/bolna/blob/master/bolna/synthesizer/synthesizer_pool.py): TTS provider selection · `bolna/synthesizer/synthesizer_pool.py`
- [Base synthesizer](https://github.com/bolna-ai/bolna/blob/master/bolna/synthesizer/base_synthesizer.py): TTS contract · `bolna/synthesizer/base_synthesizer.py`

### Transport adapters

- [Input handlers](https://github.com/bolna-ai/bolna/blob/master/bolna/input_handlers/default.py): transport ingress · `bolna/input_handlers/default.py`
- [Twilio input adapter](https://github.com/bolna-ai/bolna/blob/master/bolna/input_handlers/telephony_providers/twilio.py): telephony ingress · `bolna/input_handlers/telephony_providers/twilio.py`
- [Output handlers](https://github.com/bolna-ai/bolna/blob/master/bolna/output_handlers/default.py): transport egress · `bolna/output_handlers/default.py`
- [Twilio output adapter](https://github.com/bolna-ai/bolna/blob/master/bolna/output_handlers/telephony_providers/twilio.py): telephony egress · `bolna/output_handlers/telephony_providers/twilio.py`

### State & external services

- [Conversation history](https://github.com/bolna-ai/bolna/blob/master/bolna/helpers/conversation_history.py): conversation state · `bolna/helpers/conversation_history.py`
- [Cache abstraction](https://github.com/bolna-ai/bolna/blob/master/bolna/memory/cache/base_cache.py): memory contract · `bolna/memory/cache/base_cache.py`
- [RAG service client](https://github.com/bolna-ai/bolna/blob/master/bolna/helpers/rag_service_client.py): knowledge service · `bolna/helpers/rag_service_client.py`

## Connections

- Configuration models → Assistant: configures
- Assistant → Assistant manager: delegates execution
- Assistant manager → Task manager: coordinates tasks
- Task manager → Base agent: instantiates
- Base agent → Contextual conversational agent: implemented by
- Base agent → Graph workflow agents: implemented by
- Input handlers → Transcriber pool: audio input
- Twilio input adapter → Input handlers: vendor events
- Transcriber pool → Base transcriber: selects provider
- Transcriber pool → Contextual conversational agent: transcript
- Contextual conversational agent → LLM abstraction: streams prompts
- Graph workflow agents → LLM abstraction: uses
- LLM abstraction → Function calling: tool calls
- Function calling → Contextual conversational agent: tool results
- Contextual conversational agent → Synthesizer pool: response text
- Synthesizer pool → Base synthesizer: selects provider
- Synthesizer pool → Output handlers: synthesized audio
- Output handlers → Twilio output adapter: telephony audio
- Assistant manager → Interruption manager: handles barge-in
- Assistant manager → Voicemail handler: handles terminal calls
- Contextual conversational agent → Conversation history: reads and updates
- Contextual conversational agent → Cache abstraction: uses
- Contextual conversational agent → RAG service client: retrieves knowledge
