### Quick Start Local Setup

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Execute the provided shell script to check dependencies, build services, and start the environment in detached mode.

```bash
cd local_setup
chmod +x start.sh
./start.sh
```

--------------------------------

### Quick Start Docker Setup

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Execute this script to automatically set up Docker dependencies, build services with BuildKit, and start them in detached mode.

```bash
chmod +x start.sh
./start.sh
```

--------------------------------

### Configure Pipeline Examples

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/07-tools-functions.md

Examples of defining pipeline lists for different execution scenarios.

```python
# Standard voice pipeline: transcribe → LLM → synthesize
pipelines = [["transcriber", "llm", "synthesizer"]]

# Parallel pipelines: voice + text
pipelines = [
    ["transcriber", "llm", "synthesizer"],
    ["llm"]  # Text-only path
]

# Multiple independent paths
pipelines = [
    ["transcriber", "llm"],  # ASR + LLM
    ["llm"]                  # Text input
]
```

--------------------------------

### Initialize GraphAgent

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/03-llm-agents.md

Example setup for a graph-based agent using nodes, edges, and a GraphAgentConfig instance.

```python
from bolna.models import (
    LlmAgent, GraphAgentConfig, GraphNode, GraphEdge,
    ExpressionCondition, ExpressionGroup, ExpressionOperator
)

nodes = [
    GraphNode(
        id="greeting",
        node_type="llm",
        prompt="Greet the user and ask how you can help",
        edges=[
            GraphEdge(
                to_node_id="support",
                condition="User wants technical support",
                condition_type="llm"
            ),
            GraphEdge(
                to_node_id="billing",
                condition="User has billing questions",
                condition_type="llm"
            )
        ]
    ),
    GraphNode(
        id="support",
        node_type="llm",
        prompt="Provide technical support",
        edges=[
            GraphEdge(
                to_node_id="goodbye",
                condition_type="unconditional"
            )
        ]
    )
]

graph_config = GraphAgentConfig(
    model="gpt-4o-mini",
    provider="openai",
    agent_information="You are a helpful customer support agent",
    nodes=nodes,
    current_node_id="greeting"
)

llm_agent = LlmAgent(
    agent_type="graph_agent",
    agent_flow_type="streaming",
    llm_config=graph_config
)
```

--------------------------------

### Implement a tool function example

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/07-tools-functions.md

Example of creating a ToolFunction and wrapping it in a ToolDescription for weather lookup.

```python
from bolna.models import ToolFunction, ToolDescription

# Define a weather lookup function
tool_func = ToolFunction(
    name="get_weather",
    description="Get current weather for a location",
    parameters={
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City name or coordinates"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        "required": ["location"]
    }
)

tool_desc = ToolDescription(
    type="function",
    function=tool_func
)
```

--------------------------------

### Router Node Configuration Examples

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/08-graph-agents.md

Demonstrates invalid configurations due to missing catch-all edges or prohibited prompts, alongside a valid router node setup.

```python
# Invalid - router with prompt (rejected)
GraphNode(
    id="bad_router",
    node_type="router",
    prompt="This will fail",  # ❌ Error: routers cannot speak
)

# Invalid - router without catch-all (rejected)
GraphNode(
    id="bad_router",
    node_type="router",
    edges=[
        GraphEdge(to_node_id="a", condition_type="llm"),  # Conditional
        GraphEdge(to_node_id="b", condition_type="llm"),  # Conditional
        # ❌ Error: no catch-all
    ]
)

# Valid - router with catch-all
GraphNode(
    id="good_router",
    node_type="router",
    edges=[
        GraphEdge(to_node_id="a", condition_type="llm"),
        GraphEdge(to_node_id="b", condition_type="llm"),
        GraphEdge(to_node_id="default", condition_type="unconditional")  # ✓ Catch-all
    ]
)
```

--------------------------------

### Configure Local LLM Agents

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/12-providers-supported.md

Initialization examples for local providers like Ollama and VLLM.

```python
SimpleLlmAgent(
    provider="ollama",
    model="llama2",
    base_url="http://localhost:11434"
)
```

```python
SimpleLlmAgent(
    provider="vllm",
    model="meta-llama/Llama-2-7b",
    base_url="http://localhost:8000"
)
```

--------------------------------

### Initialize RerankerConfig Instances

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/04-rag-and-vectors.md

Examples of configuring the reranker with different settings for performance and quality.

```python
# Disable reranking (default)
reranker = RerankerConfig(enabled=False)

# Enable with BGE-base reranker
reranker = RerankerConfig(
    enabled=True,
    model_type="bge-base",
    candidate_count=30,
    final_count=5
)

# Aggressive reranking for quality
reranker = RerankerConfig(
    enabled=True,
    model_type="bge-large",
    candidate_count=50,
    final_count=3
)
```

--------------------------------

### Configure OpenAI LLM Agent

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/12-providers-supported.md

Initialization example for an agent using the OpenAI provider.

```python
SimpleLlmAgent(
    provider="openai",
    model="gpt-4o-mini",
    temperature=0.3,
    max_tokens=500
)
```

--------------------------------

### Build and Run Services

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Commands to manually build and start the Docker containers for the Bolna platform.

```bash
docker compose build
```

```bash
docker compose up -d
```

--------------------------------

### Run Specific Services

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Start only the required application and telephony provider containers.

```bash
docker compose up -d bolna-app twilio-app
# or
docker compose up -d bolna-app plivo-app
```

--------------------------------

### Assistant Execution Example

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/10-agent-managers.md

Demonstrates how to configure an assistant with tasks and iterate over the output generated by the manager's run method.

```python
from bolna.assistant import Assistant
from bolna.models import LlmAgent, SimpleLlmAgent, Transcriber, Synthesizer

async def main():
    assistant = Assistant(name="demo")
    assistant.add_task(
        task_type="conversation",
        llm_agent=LlmAgent(
            agent_type="simple_llm_agent",
            agent_flow_type="streaming",
            llm_config=SimpleLlmAgent(provider="openai", model="gpt-4o-mini")
        ),
        transcriber=Transcriber(provider="deepgram"),
        synthesizer=Synthesizer(provider="elevenlabs", provider_config={...})
    )
    
    async for task_index, output in assistant.manager.run():
        component = output.get("component")
        data = output.get("data")
        
        if component == "transcriber":
            print(f"User said: {data}")
        elif component == "llm":
            print(f"Agent: {data}")
        elif component == "synthesizer":
            # Handle audio bytes
            pass
```

--------------------------------

### ExpressionCondition Usage Examples

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/08-graph-agents.md

Examples demonstrating numeric comparison, string containment, existence checks, and set membership using ExpressionCondition.

```python
from bolna.models import ExpressionCondition, ExpressionOperator

# Numeric comparison
age_check = ExpressionCondition(
    variable="context.age",
    operator=ExpressionOperator.GTE,
    value=18
)

# String contains
has_code = ExpressionCondition(
    variable="referral_code",
    operator=ExpressionOperator.CONTAINS,
    value="PREMIUM"
)

# Existence check
has_profile = ExpressionCondition(
    variable="user.profile",
    operator=ExpressionOperator.EXISTS
)

# Set membership
language_check = ExpressionCondition(
    variable="language",
    operator=ExpressionOperator.IN,
    value=["en", "es", "fr"]
)
```

--------------------------------

### Configure Transcriber Instances

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/02-transcriber-synthesizer.md

Examples of initializing the Transcriber model for different providers and configurations.

```python
from bolna.models import Transcriber

# Deepgram with streaming
transcriber = Transcriber(
    provider="deepgram",
    model="nova-2",
    stream=True,
    language="en",
    encoding="linear16",
    vad_threshold=0.5
)

# Azure with specific settings
transcriber = Transcriber(
    provider="azure",
    language="en",
    stream=True,
    sampling_rate=16000
)

# Multilingual support
transcriber = Transcriber(
    provider="deepgram",
    multilingual={"enabled": True},
    language_hints=["en", "es", "fr"]
)
```

--------------------------------

### Retrieve Agent via cURL

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/09-endpoints-api.md

Example request to fetch agent details using a GET request.

```bash
curl -X GET http://localhost:5000/agent/550e8400-e29b-41d4-a716-446655440000
```

--------------------------------

### Configure API Tools

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/07-tools-functions.md

Example of mapping tool-specific parameters within the ToolsConfig model.

```python
from bolna.models import ToolsConfig, ToolModel

tools_config = ToolsConfig(
    api_tools=ToolModel(
        tools=[...],  # Tool definitions
        tools_params={
            "get_weather": {
                "api_key": "weather_api_key",
                "base_url": "https://api.weather.com"
            },
            "check_availability": {
                "db_connection": "postgres://..."
            }
        }
    )
)
```

--------------------------------

### List All Agents Request

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/09-endpoints-api.md

Example cURL command to fetch all agents from the local server.

```bash
curl -X GET http://localhost:5000/all
```

--------------------------------

### Integrate Tools with Assistant

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/07-tools-functions.md

Full setup for defining a tool function and attaching it to an assistant configuration.

```python
from bolna.models import (
    ToolFunction, ToolDescription, ToolModel,
    ToolsConfig, Assistant, LlmAgent, SimpleLlmAgent,
    Transcriber, Synthesizer
)

# Define tools
get_weather_tool = ToolFunction(
    name="get_weather",
    description="Get weather for a location",
    parameters={
        "type": "object",
        "properties": {
            "location": {"type": "string"}
        },
        "required": ["location"]
    }
)

tools = ToolModel(
    tools=[ToolDescription(type="function", function=get_weather_tool)],
    tools_params={
        "get_weather": {
            "api_key": "YOUR_WEATHER_API_KEY",
            "base_url": "https://api.weather.com"
        }
    }
)

# Create assistant with tools
assistant = Assistant(name="weather_agent")

tools_config = ToolsConfig(
    llm_agent=LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini"
        )
    ),
    transcriber=Transcriber(provider="deepgram"),
    synthesizer=Synthesizer(provider="elevenlabs", provider_config={...}),
    api_tools=tools
)

# Tools are automatically available to the LLM
```

--------------------------------

### Configure Azure OpenAI LLM

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/12-providers-supported.md

Initialization example for an agent using the Azure OpenAI provider, requiring a base URL.

```python
Llm(
    provider="azure",
    model="gpt-4-deployment-name",
    base_url="https://your-resource.openai.azure.com/"
)
```

--------------------------------

### Initialize LanceDBProviderConfig

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/04-rag-and-vectors.md

Examples of initializing the configuration with either a single vector ID or multiple vector IDs.

```python
from bolna.models import LanceDBProviderConfig, RerankerConfig

config = LanceDBProviderConfig(
    vector_id="customer_knowledge_base",
    similarity_top_k=5,
    score_threshold=0.15,
    reranker=RerankerConfig(
        enabled=True,
        model_type="bge-base",
        candidate_count=20,
        final_count=5
    )
)

# Multiple knowledge bases
config_multi = LanceDBProviderConfig(
    vector_ids=["kb_en", "kb_es", "kb_fr"],
    similarity_top_k=10,
    reranker=RerankerConfig(enabled=False)
)
```

--------------------------------

### Configure RAG and Graph Agent

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/04-rag-and-vectors.md

Demonstrates the full setup process including reranker configuration, vector store initialization, and integration into a graph agent with local and global RAG settings.

```python
from bolna.models import (
    RagConfig, VectorStore, LanceDBProviderConfig, RerankerConfig,
    GraphAgentConfig, GraphNode, LlmAgent
)

# Step 1: Configure reranking
reranker = RerankerConfig(
    enabled=True,
    model_type="bge-base",
    candidate_count=20,
    final_count=5
)

# Step 2: Configure vector store
vector_store = VectorStore(
    provider="lancedb",
    provider_config=LanceDBProviderConfig(
        vector_id="company_knowledge_base",
        similarity_top_k=5,
        score_threshold=0.2,
        reranker=reranker
    )
)

# Step 3: Configure global RAG
rag_config = RagConfig(
    vector_store=vector_store,
    similarity_top_k=5
)

# Step 4: Use in graph agent
nodes = [
    GraphNode(
        id="support",
        node_type="llm",
        prompt="Use the knowledge base to answer support questions",
        rag_config=rag_config,  # Local RAG config
        edges=[]
    ),
    GraphNode(
        id="general",
        node_type="llm",
        prompt="Use the global knowledge base for general inquiries",
        # Uses global rag_config from GraphAgentConfig
        edges=[]
    )
]

graph_config = GraphAgentConfig(
    model="gpt-4o-mini",
    provider="openai",
    agent_information="Knowledge-based support agent",
    nodes=nodes,
    current_node_id="support",
    rag_config=rag_config  # Global RAG config (fallback)
)

llm_agent = LlmAgent(
    agent_type="graph_agent",
    agent_flow_type="streaming",
    llm_config=graph_config
)
```

--------------------------------

### Handle BolnaComponentError

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/06-exceptions-errors.md

Example of catching and accessing context attributes from a BolnaComponentError.

```python
from bolna.exceptions import BolnaComponentError

try:
    # Some component operation
    pass
except BolnaComponentError as e:
    print(f"Error in {e.component}: {e}")
    if e.provider:
        print(f"Provider: {e.provider}")
    if e.model:
        print(f"Model: {e.model}")
```

--------------------------------

### Configure Node Types

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/08-graph-agents.md

Examples of initializing different node types for LLM interaction, static responses, and routing logic.

```python
GraphNode(
    id="greeting",
    node_type="llm",  # Default
    prompt="Greet the user and ask how you can help",
    examples={
        "greeting_formal": "Good morning, how can I assist you?",
        "greeting_casual": "Hey there, what can I do for you?"
    },
    edges=[...]
)
```

```python
GraphNode(
    id="goodbye",
    node_type="static",
    static_message="Thank you for calling. Goodbye!"
)
```

```python
GraphNode(
    id="intent_router",
    node_type="router",
    # Cannot have prompt or static_message
    edges=[...]  # Must have unconditional catch-all
)
```

--------------------------------

### Handle LLMError

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/06-exceptions-errors.md

Example of catching LLM-specific errors.

```python
from bolna.exceptions import LLMError

try:
    # LLM operation
    pass
except LLMError as e:
    print(f"LLM failed with provider {e.provider}: {e}")
    # Handle LLM-specific error
```

--------------------------------

### Usage example for ConversationHistory

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/11-helpers-utilities.md

Demonstrates initializing history, setting a system prompt, and appending various message types.

```python
from bolna.helpers.conversation_history import ConversationHistory

history = ConversationHistory()
history.setup_system_prompt("You are a helpful assistant.")
history.append_welcome_message("Hello, how can I help you today?")
history.append_user("What's the weather?")
history.append_assistant("I don't have access to weather data.")
```

--------------------------------

### Initialize RagConfig with LanceDB

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/04-rag-and-vectors.md

Example of instantiating a RagConfig object using the LanceDB provider with reranking enabled.

```python
from bolna.models import (
    RagConfig, VectorStore, LanceDBProviderConfig, RerankerConfig
)

rag_config = RagConfig(
    vector_store=VectorStore(
        provider="lancedb",
        provider_config=LanceDBProviderConfig(
            vector_id="my_knowledge_base",
            similarity_top_k=5,
            reranker=RerankerConfig(
                enabled=True,
                model_type="bge-base",
                candidate_count=20,
                final_count=5
            )
        )
    )
)
```

--------------------------------

### Get All Agents

Source: https://github.com/bolna-ai/bolna/blob/master/API.md

Retrieves all agents from the system.

```APIDOC
## GET /all

### Description
Retrieves all agents from the system.

### Method
GET

### Endpoint
/all

### Response
#### Success Response (200 OK)
- **agents** (array) - A list of agents.
  - **agent_id** (string) - The unique identifier of the agent.
  - **data** (object) - Contains the agent's configuration and prompts.
    - **agent_config** (object) - The agent's configuration.
    - **agent_prompts** (object) - The agent's prompts.

#### Response Example
```json
{
  "agents": [
    {
      "agent_id": "string",
      "data": {
        "agent_config": {
          "agent_name": "Alfred",
          "agent_type": "other",
          "tasks": []
        },
        "agent_prompts": {}
      }
    }
  ]
}
```
```

--------------------------------

### Configure Deepgram Transcriber

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/12-providers-supported.md

Example configuration for initializing the Deepgram transcriber with specific model and stream settings.

```python
Transcriber(
    provider="deepgram",
    model="nova-2",  # or nova-1, nova
    stream=True,
    language="en",
    encoding="linear16"
)
```

--------------------------------

### Create Agent via cURL

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/09-endpoints-api.md

Example command to create a new support agent using the POST /agent endpoint.

```bash
curl -X POST http://localhost:5000/agent \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "agent_name": "support_bot",
      "agent_type": "other",
      "tasks": [{
        "task_type": "conversation",
        "toolchain": {
          "execution": "parallel",
          "pipelines": [["transcriber", "llm", "synthesizer"]]
        },
        "tools_config": {
          "input": {"format": "wav", "provider": "twilio"},
          "output": {"format": "wav", "provider": "twilio"},
          "transcriber": {
            "provider": "deepgram",
            "model": "nova-2",
            "stream": true
          },
          "llm_agent": {
            "agent_type": "simple_llm_agent",
            "agent_flow_type": "streaming",
            "llm_config": {
              "provider": "openai",
              "model": "gpt-4o-mini"
            }
          },
          "synthesizer": {
            "provider": "elevenlabs",
            "stream": true,
            "provider_config": {
              "voice": "George",
              "voice_id": "JBFqnCBsd6RMkjVDRZzb",
              "model": "eleven_turbo_v2_5"
            }
          }
        }
      }],
      "agent_welcome_message": "Hello, how can I help?"
    },
    "agent_prompts": {
      "task_1": {
        "system_prompt": "You are a helpful support agent..."
      }
    }
  }'
```

--------------------------------

### Run Specific Docker Services

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Start only specific services, such as the Bolna application and either the Twilio or Plivo app. Useful for targeted development or testing.

```bash
docker compose up -d bolna-app twilio-app
```

```bash
docker compose up -d bolna-app plivo-app
```

--------------------------------

### Run All Docker Services

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Start all defined Docker services in detached mode. This is the standard way to run the full local environment.

```bash
docker compose up -d
```

--------------------------------

### Configure GraphEdge Routing Types

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/08-graph-agents.md

Examples of different routing strategies including LLM-based, expression-based, unconditional, and event-based transitions.

```python
GraphEdge(
    to_node_id="billing",
    condition="User is asking about billing",
    condition_type="llm",
    function_description="Transfer to billing node"
)
```

```python
GraphEdge(
    to_node_id="premium_support",
    condition="User is premium customer",
    condition_type="expression",
    expression=ExpressionGroup(
        logic="and",
        conditions=[
            ExpressionCondition(
                variable="user_tier",
                operator="eq",
                value="premium"
            ),
            ExpressionCondition(
                variable="support_available",
                operator="exists"
            )
        ]
    )
)
```

```python
GraphEdge(
    to_node_id="end",
    condition_type="unconditional"
)
```

```python
GraphEdge(
    to_node_id="escalation",
    condition="Escalation requested",
    condition_type="event",
    event_name="escalate_call"
)
```

--------------------------------

### Usage Examples for LocalizedText

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/05-types-enums.md

Demonstrates assigning both single-language strings and multilingual dictionary objects to a LocalizedText variable.

```python
# Single language
message = "Hello, how can I help?"

# Multilingual
message = {
    "en": "Hello, how can I help?",
    "es": "Hola, ¿cómo puedo ayudarte?",
    "fr": "Bonjour, comment puis-je vous aider?"
}
```

--------------------------------

### Configure Graph Agent with RAG

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/08-graph-agents.md

Setup for a graph agent including knowledge base configuration using LanceDB.

```python
from bolna.models import (
    LlmAgent, GraphAgentConfig, GraphNode, GraphEdge,
    ExpressionCondition, ExpressionGroup, ExpressionOperator, ExpressionLogic,
    NodeType, EdgeConditionType, VariableType, RagConfig, VectorStore, LanceDBProviderConfig
)

# Define knowledge base
rag_config = RagConfig(
    vector_store=VectorStore(
        provider="lancedb",
        provider_config=LanceDBProviderConfig(
            vector_id="support_docs",
            similarity_top_k=5
        )
    )
)
```

--------------------------------

### Implement ExpressionGroup Logic

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/08-graph-agents.md

Examples of creating logical groups using AND and OR operators for conditional evaluation.

```python
from bolna.models import ExpressionGroup, ExpressionCondition, ExpressionLogic, ExpressionOperator

# User is premium AND in US
premium_us = ExpressionGroup(
    logic=ExpressionLogic.AND,
    conditions=[
        ExpressionCondition(variable="tier", operator=ExpressionOperator.EQ, value="premium"),
        ExpressionCondition(variable="country", operator=ExpressionOperator.EQ, value="US")
    ]
)

# Language is English OR Spanish
bilingual = ExpressionGroup(
    logic=ExpressionLogic.OR,
    conditions=[
        ExpressionCondition(variable="language", operator=ExpressionOperator.EQ, value="en"),
        ExpressionCondition(variable="language", operator=ExpressionOperator.EQ, value="es")
    ]
)
```

--------------------------------

### Track Latency in Output Meta Info

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/10-agent-managers.md

Example structure of the meta_info field within an output object containing component latency data.

```python
output = {
    "component": "llm",
    "data": "Hello, how can I help?",
    "meta_info": {
        "component_latencies": {
            "transcriber": 0.234,
            "llm": 1.456,
            "synthesizer": 0.789,
            "total": 2.479
        }
    }
}
```

--------------------------------

### Initialize SimpleLlmAgent

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/03-llm-agents.md

Demonstrates how to instantiate an LlmAgent with a SimpleLlmAgent configuration.

```python
from bolna.models import LlmAgent, SimpleLlmAgent

llm_agent = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="openai",
        model="gpt-4o-mini",
        temperature=0.3,
        max_tokens=500
    )
)
```

--------------------------------

### Initialize IOModel Instances

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/07-tools-functions.md

Demonstrates creating IOModel instances for specific telephony providers.

```python
from bolna.models import IOModel

# Twilio input/output
input_handler = IOModel(
    provider="twilio",
    format="wav"
)

output_handler = IOModel(
    provider="twilio",
    format="wav"
)

# Default (file-based)
default_io = IOModel(
    provider="default",
    format="wav"
)
```

--------------------------------

### Assistant.__init__

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/01-core-classes.md

Initializes a new Assistant instance.

```APIDOC
## Assistant(name: str = "trial_agent")

### Description
Initializes a new Assistant instance with a specified name identifier.

### Parameters
- **name** (str) - Optional - Name identifier for the assistant (default: "trial_agent")
```

--------------------------------

### Handle TranscriberError

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/06-exceptions-errors.md

Example of catching and inspecting TranscriberError messages.

```python
from bolna.exceptions import TranscriberError

try:
    # Transcription operation
    pass
except TranscriberError as e:
    if "connection" in str(e):
        # Handle connection error
        pass
    elif "language" in str(e):
        # Handle unsupported language
        pass
```

--------------------------------

### Get dominant_language property

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/11-helpers-utilities.md

Retrieves the currently detected language code.

```python
@property
def dominant_language(self) -> Optional[str]
```

--------------------------------

### Configure and Add Assistant Task

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/01-core-classes.md

Demonstrates initializing an assistant and configuring its transcriber, LLM, and synthesizer components before adding a task.

```python
from bolna.assistant import Assistant
from bolna.models import Transcriber, Synthesizer, LlmAgent, SimpleLlmAgent

assistant = Assistant(name="support_agent")

# Configure audio input
transcriber = Transcriber(provider="deepgram", model="nova-2")

# Configure LLM
llm_agent = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="openai",
        model="gpt-4o-mini"
    )
)

# Configure audio output
synthesizer = Synthesizer(
    provider="elevenlabs",
    provider_config={"voice": "John", "voice_id": "abc123", "model": "eleven_turbo_v2_5"}
)

assistant.add_task(
    task_type="conversation",
    llm_agent=llm_agent,
    transcriber=transcriber,
    synthesizer=synthesizer
)
```

--------------------------------

### Get Agent

Source: https://github.com/bolna-ai/bolna/blob/master/API.md

Retrieves an agent's information by agent id.

```APIDOC
## GET /agent/{agent_id}

### Description
Retrieves an agent's information by agent id.

### Method
GET

### Endpoint
/agent/{agent_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - Unique identifier of the agent
```

--------------------------------

### GET /agent/{agent_id}

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/09-endpoints-api.md

Retrieves the configuration and prompts for a specific agent by its UUID.

```APIDOC
## GET /agent/{agent_id}

### Description
Retrieves an agent's configuration by ID.

### Method
GET

### Endpoint
/agent/{agent_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - Agent UUID

### Response
#### Success Response (200)
- **agent_id** (string) - Agent UUID
- **data** (object) - Agent configuration and prompts

### Response Example
{
  "agent_id": "uuid-string",
  "data": {
    "agent_config": {},
    "agent_prompts": {}
  }
}
```

--------------------------------

### BaseSynthesizer.__init__

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/02-transcriber-synthesizer.md

Initializes the synthesizer with task management, streaming configuration, and buffer settings.

```APIDOC
## Constructor

### Signature
`def __init__(task_manager_instance: Optional[Any] = None, stream: bool = True, buffer_size: int = 40, event_loop: Optional[Any] = None) -> None`

### Parameters
- **task_manager_instance** (Optional[Any]) - Optional - Reference to task manager
- **stream** (bool) - Optional - Enable streaming output (Default: True)
- **buffer_size** (int) - Optional - Character buffer for chunking (Default: 40)
- **event_loop** (Optional[Any]) - Optional - Async event loop
```

--------------------------------

### Handle SynthesizerError

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/06-exceptions-errors.md

Example of catching and handling SynthesizerError based on error message content.

```python
from bolna.exceptions import SynthesizerError

try:
    # Synthesis operation
    pass
except SynthesizerError as e:
    if "voice" in str(e):
        # Voice not found, try alternative
        pass
```

--------------------------------

### Execute Assistant Tasks

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/01-core-classes.md

Shows how to run the assistant and iterate over the resulting async generator.

```python
async def main():
    assistant = Assistant(name="demo")
    # ... add tasks ...
    
    async for output in assistant.execute():
        print(output)

asyncio.run(main())
```

--------------------------------

### Instantiate Custom Manager

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/10-agent-managers.md

Shows manual configuration of an AssistantManager with custom queues and agent settings.

```python
from bolna.agent_manager import AssistantManager
from bolna.models import AgentModel, Task, ToolsConfig, ToolsChainModel

# Build configuration manually
agent_config = {
    "agent_name": "custom_agent",
    "tasks": [...]
}

# Create manager with custom websocket/queues
input_queue = asyncio.Queue()
output_queue = asyncio.Queue()

manager = AssistantManager(
    agent_config=agent_config,
    ws=None,
    input_queue=input_queue,
    output_queue=output_queue
)

# Run with custom I/O
async for task_index, output in manager.run():
    await output_queue.put(output)
```

--------------------------------

### Delete Agent via cURL

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/09-endpoints-api.md

Example request to remove an agent using a DELETE request.

```bash
curl -X DELETE http://localhost:5000/agent/550e8400-e29b-41d4-a716-446655440000
```

--------------------------------

### TaskManager.welcome_pcm_upsampled

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/10-agent-managers.md

Synthesizes a welcome message into upsampled PCM audio bytes.

```APIDOC
## TaskManager.welcome_pcm_upsampled

### Description
Synthesizes the provided welcome message as upsampled PCM audio using the specified synthesizer instance.

### Parameters
- **welcome_message** (str) - Optional - Welcome text to synthesize
- **synthesizer** (BaseSynthesizer) - Required - Synthesizer instance

### Returns
- **bytes** - PCM audio bytes or None
```

--------------------------------

### Retrieve All Agents Response Schema

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/09-endpoints-api.md

The expected JSON structure returned by the GET /all endpoint.

```json
{
  "agents": [
    {
      "agent_id": "uuid-string",
      "data": {
        "agent_config": { /* configuration */ },
        "agent_prompts": { /* prompts */ }
      }
    }
  ]
}
```

--------------------------------

### Define system prompt method

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/11-helpers-utilities.md

Sets the initial system prompt for the conversation.

```python
def setup_system_prompt(self, prompt: str) -> None
```

--------------------------------

### Run voice assistant with environment variables

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Sets required API keys and executes the voice assistant script.

```bash
export OPENAI_API_KEY=...
export DEEPGRAM_AUTH_TOKEN=...
export ELEVENLABS_API_KEY=...
python examples/simple_assistant.py
```

--------------------------------

### Update Agent via cURL

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/09-endpoints-api.md

Example request to update an agent's configuration using a PUT request.

```bash
curl -X PUT http://localhost:5000/agent/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -d '{ /* updated config */ }'
```

--------------------------------

### Construct GET request URLs

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/11-helpers-utilities.md

Appends query parameters to a base URL to form a complete request string.

```python
def build_get_url(
    base_url: str,
    query_params: Dict[str, Any]
) -> str
```

--------------------------------

### Build Docker Images

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Build all Docker images defined in the docker-compose file. Ensure BuildKit is enabled for optimal performance.

```bash
docker compose build
```

--------------------------------

### Get Agent Configuration Response

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/09-endpoints-api.md

The expected JSON response structure when successfully retrieving an agent's configuration.

```json
{
  "agent_id": "uuid-string",
  "data": {
    "agent_config": { /* agent configuration */ },
    "agent_prompts": { /* prompts */ }
  }
}
```

--------------------------------

### Get All Agents Response Body

Source: https://github.com/bolna-ai/bolna/blob/master/API.md

The response when retrieving all agents. It contains a list of agents, each with its ID and configuration data.

```json
{
  "agents": [
    {
      "agent_id": "string",
      "data": {
        "agent_config": {
          "agent_name": "Alfred",
          "agent_type": "other",
          "tasks": []
        },
        "agent_prompts": {}
      }
    }
  ]
}
```

--------------------------------

### Enable BuildKit for Docker

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Set these environment variables to enable BuildKit for faster Docker image builds.

```bash
export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1
```

--------------------------------

### Run text-only assistant with environment variables

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Sets the OpenAI API key and executes the text-only assistant script.

```bash
export OPENAI_API_KEY=...
python examples/text_only_assistant.py
```

--------------------------------

### Configure Multi-Agent Switching

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/07-tools-functions.md

Define the switch tool description, handoff messages, and agent names to enable agent transfers.

```python
from bolna.models import ToolsConfig

tools_config = ToolsConfig(
    switch_tool_description="Transfer the call to the appropriate department",
    switch_handoff_messages={
        "sales": "Transferring you to our sales team...",
        "support": "Connecting you with technical support...",
        "billing": "Transferring to billing department..."
    },
    agent_names={
        "sales": "Sales Representative",
        "support": "Technical Support",
        "billing": "Billing Agent"
    }
)
```

--------------------------------

### Synthesize Welcome Message

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/10-agent-managers.md

Method to synthesize a welcome message into upsampled PCM audio bytes using a provided synthesizer.

```python
def welcome_pcm_upsampled(
    self,
    welcome_message: Optional[str],
    synthesizer: BaseSynthesizer
) -> Optional[bytes]
```

--------------------------------

### Configure Transcriber and Synthesizer for Voice Assistant

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/02-transcriber-synthesizer.md

Initializes Deepgram transcription and ElevenLabs synthesis providers, then integrates them into a Bolna assistant task.

```python
from bolna.models import Transcriber, Synthesizer, ElevenLabsConfig

# Transcriber setup
transcriber = Transcriber(
    provider="deepgram",
    model="nova-2",
    stream=True,
    language="en",
    encoding="linear16"
)

# Synthesizer with ElevenLabs
synthesizer = Synthesizer(
    provider="elevenlabs",
    stream=True,
    audio_format="wav",
    provider_config=ElevenLabsConfig(
        voice="George",
        voice_id="JBFqnCBsd6RMkjVDRZzb",
        model="eleven_turbo_v2_5",
        temperature=0.5,
        speed=1.0
    )
)

# Use in assistant
from bolna.assistant import Assistant
from bolna.models import LlmAgent, SimpleLlmAgent

assistant = Assistant(name="voice_agent")
assistant.add_task(
    task_type="conversation",
    llm_agent=LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(provider="openai", model="gpt-4o-mini")
    ),
    transcriber=transcriber,
    synthesizer=synthesizer
)
```

--------------------------------

### Configure Component Logging

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/06-exceptions-errors.md

Implementation of Bolna's logger to capture component-specific errors.

```python
from bolna.helpers.logger_config import configure_logger

logger = configure_logger(__name__)

try:
    # operation
    pass
except BolnaComponentError as e:
    # Component errors are automatically logged with context
    logger.error(f"Component error in {e.component}: {e}")
```

--------------------------------

### Create a text-only assistant

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Configures an agent pipeline without audio components, enabling direct textual input.

```python
import asyncio
from bolna.assistant import Assistant
from bolna.models import LlmAgent, SimpleLlmAgent


async def main():
    assistant = Assistant(name="text_only_agent")

    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.2,
        ),
    )

    # No transcriber/synthesizer; enable a text-only pipeline
    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        enable_textual_input=True,
    )

    async for chunk in assistant.execute():
        print(chunk)


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Catching Specific Component Errors

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/06-exceptions-errors.md

Demonstrates how to handle distinct exceptions for different Bolna components like LLM, Transcriber, and Synthesizer.

```python
from bolna.exceptions import LLMError, TranscriberError, SynthesizerError, BolnaComponentError

async def execute_with_error_handling():
    try:
        async for chunk in assistant.execute():
            print(chunk)
    except LLMError as e:
        print(f"LLM failed: {e}")
        # Fallback to alternative LLM or graceful degradation
    except TranscriberError as e:
        print(f"Transcription failed: {e}")
        # Fall back to text-only mode
    except SynthesizerError as e:
        print(f"Synthesis failed: {e}")
        # Continue without audio output
    except BolnaComponentError as e:
        print(f"Unknown component error: {e.component}: {e}")
        # Generic component error handling
    except Exception as e:
        print(f"Unexpected error: {e}")
```

--------------------------------

### Initialize BaseSynthesizer

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/02-transcriber-synthesizer.md

Constructor for the base synthesizer class, allowing configuration of streaming, buffer size, and event loop integration.

```python
def __init__(
    self,
    task_manager_instance: Optional[Any] = None,
    stream: bool = True,
    buffer_size: int = 40,
    event_loop: Optional[Any] = None
) -> None
```

--------------------------------

### Configure Smallest AI

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/12-providers-supported.md

Configuration schema for Smallest AI ultra-low latency TTS.

```python
SmallestConfig(
    voice_id: str,
    language: str,
    voice: str,
    model: str
)
```

--------------------------------

### AssistantManager.run()

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/10-agent-managers.md

The run method is the main execution loop that orchestrates all pipeline components, yielding task outputs as they are processed.

```APIDOC
## async def run(self) -> AsyncGenerator[Tuple[int, Dict[str, Any]], None]

### Description
Main execution loop that orchestrates all pipeline components (transcriber, LLM, synthesizer). It yields a tuple containing the task index and the output dictionary.

### Yields
- **task_index** (int) - The index of the current task being executed.
- **task_output** (Dict) - The output data from the component.

### Output Dictionary Structure
- **component** (string) - The component type: "transcriber", "llm", "synthesizer", or "error".
- **data** (string) - The processed data (e.g., transcribed text, LLM response, or audio data).
- **meta_info** (dict) - Metadata including timestamp, component_latency, sequence_id, and is_final status.
```

--------------------------------

### Assistant.execute

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/01-core-classes.md

Executes the assistant tasks.

```APIDOC
## execute() -> AsyncGenerator[Dict[str, Any], None]

### Description
Executes the assistant tasks and yields streaming results as an async generator.

### Returns
- **AsyncGenerator** - Yields task output dictionaries with component results
```

--------------------------------

### Create a voice-enabled assistant

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Configures a full pipeline with Deepgram for transcription, OpenAI for LLM processing, and ElevenLabs for speech synthesis.

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


async def main():
    assistant = Assistant(name="demo_agent")

    # Configure audio input (ASR)
    transcriber = Transcriber(provider="deepgram", model="nova-2", stream=True, language="en")

    # Configure LLM
    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.3,
        ),
    )

    # Configure audio output (TTS)
    synthesizer = Synthesizer(
        provider="elevenlabs",
        provider_config=ElevenLabsConfig(voice="George", voice_id="JBFqnCBsd6RMkjVDRZzb", model="eleven_turbo_v2_5"),
        stream=True,
        audio_format="wav",
    )

    # Build a single coherent pipeline: transcriber -> llm -> synthesizer
    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        transcriber=transcriber,
        synthesizer=synthesizer,
        enable_textual_input=False,
    )

    # Stream results
    async for chunk in assistant.execute():
        print(chunk)


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Project Directory Structure

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/00-index.md

Visual representation of the Bolna project file hierarchy.

```text
bolna/
├── __init__.py                          # Package initialization
├── assistant.py                         # Assistant class (main entry point)
├── models.py                            # Pydantic configuration models
├── enums.py                             # Enumerations
├── exceptions.py                        # Exception classes
├── constants.py                         # Constants and defaults
├── providers.py                         # Provider registry
├── agent_manager/                       # Task orchestration
│   ├── assistant_manager.py
│   ├── base_manager.py
│   ├── task_manager.py
│   ├── interruption_manager.py
│   └── voicemail_handler.py
├── agent_types/                         # Agent implementations
│   ├── base_agent.py
│   ├── contextual_conversational_agent.py
│   ├── graph_agent.py
│   ├── graph_based_conversational_agent.py
│   ├── extraction_agent.py
│   ├── knowledgebase_agent.py
│   ├── summarization_agent.py
│   └── webhook_agent.py
├── transcriber/                         # STT implementations
│   ├── base_transcriber.py
│   └── [provider]_transcriber.py
├── synthesizer/                         # TTS implementations
│   ├── base_synthesizer.py
│   └── [provider]_synthesizer.py
├── input_handlers/                      # Input handlers
│   ├── default.py
│   ├── telephony.py
│   └── telephony_providers/
├── output_handlers/                     # Output handlers
│   ├── default.py
│   ├── telephony.py
│   └── telephony_providers/
├── llms/                                # LLM implementations
│   ├── base_llm.py
│   ├── openai_llm.py
│   ├── azure_llm.py
│   ├── gemini_llm.py
│   └── litellm.py
├── helpers/                             # Utility functions
│   ├── conversation_history.py
│   ├── expression_evaluator.py
│   ├── function_calling_helpers.py
│   ├── language_detector.py
│   ├── language_switcher.py
│   ├── logger_config.py
│   ├── analytics_helpers.py
│   ├── utils.py
│   └── [other helpers]
├── memory/                              # State management
└── lid/                                 # Language identification
```

--------------------------------

### Initialize LanguageSwitcher

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/11-helpers-utilities.md

Class definition for managing language switching, including resource pre-loading.

```python
class LanguageSwitcher:
    async def prewarm(self, language: str) -> None
```

--------------------------------

### Documentation File Organization

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/README.md

The directory structure for the project documentation files.

```text
00-index.md              (Master index & navigation)
01-core-classes.md       (Assistant, Agent, Task)
02-transcriber-synthesizer.md (Audio I/O)
03-llm-agents.md         (LLM configuration)
04-rag-and-vectors.md    (Knowledge bases)
05-types-enums.md        (Type system)
06-exceptions-errors.md  (Error handling)
07-tools-functions.md    (Function calling)
08-graph-agents.md       (Multi-node flows)
09-endpoints-api.md      (HTTP API)
10-agent-managers.md     (Orchestration)
11-helpers-utilities.md  (Utilities)
12-providers-supported.md (Integrations)
README.md               (This file)
```

--------------------------------

### Configure ElevenLabs

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/12-providers-supported.md

Configuration schema for ElevenLabs TTS, supporting voice parameters and speed control.

```python
ElevenLabsConfig(
    voice: str,                    # Voice name (George, Bella, etc.)
    voice_id: str,                 # Unique voice identifier
    model: str,                    # eleven_turbo_v2_5, eleven_monolingual_v1
    temperature: float = 0.5,      # Consistency (0-1)
    similarity_boost: float = 0.75, # Voice similarity (0-1)
    speed: float = 1.0,            # Speed multiplier
    style: float = 0.0             # Style exaggeration (0-1)
)
```

--------------------------------

### Configure Logger and Set Context

Source: https://github.com/bolna-ai/bolna/blob/master/_autodocs/11-helpers-utilities.md

Initializes a logger and sets context variables like call_id and agent_id for structured logging.

```python
def configure_logger(
    name: str,
    level: Optional[str] = None
) -> logging.Logger
```

```python
def set_log_context(context: Dict[str, Any]) -> None
```

```python
def get_log_context() -> Dict[str, Any]
```

```python
def clear_log_context() -> None
```

```python
from bolna.helpers.logger_config import configure_logger, set_log_context

logger = configure_logger(__name__)

set_log_context({
    "call_id": "550e8400-e29b-41d4-a716",
    "agent_id": "support_bot"
})

logger.info("Processing call")  # Logs include context

clear_log_context()
```