{"id":14366125,"url":"https://github.com/voxos-ai/bolna","last_synced_at":"2025-05-15T19:06:31.543Z","repository":{"id":212360559,"uuid":"731056335","full_name":"voxos-ai/bolna","owner":"voxos-ai","description":"End-to-end platform for building voice first multimodal agents","archived":false,"fork":false,"pushed_at":"2024-10-28T05:40:38.000Z","size":19269,"stargazers_count":418,"open_issues_count":31,"forks_count":111,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-05-11T01:03:28.723Z","etag":null,"topics":["anyscale","chatgpt-api","claude-3-sonnet","deepgram","elevenlabs","fastapi","gpt-4o","llama3","llm","mistral","openai","perplexity-api","polly","telephony","twilio","voice-assistant","websocket-chat","websockets","whisper","xtts"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voxos-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"custom":"https://api.xpaycheckout.com/link/TO8pQciS"}},"created_at":"2023-12-13T09:07:35.000Z","updated_at":"2025-05-08T04:54:35.000Z","dependencies_parsed_at":"2024-08-27T19:32:36.604Z","dependency_job_id":"c2827a9b-930b-45aa-8a89-09084308755d","html_url":"https://github.com/voxos-ai/bolna","commit_stats":{"total_commits":638,"total_committers":12,"mean_commits":"53.166666666666664","dds":0.5266457680250783,"last_synced_commit":"9dfbe93019208f70a7cbf83ef3bfb802b7c5f72b"},"previous_names":["bolna-ai/bolna","voxos-ai/bolna"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxos-ai%2Fbolna","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxos-ai%2Fbolna/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxos-ai%2Fbolna/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voxos-ai%2Fbolna/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voxos-ai","download_url":"https://codeload.github.com/voxos-ai/bolna/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254404357,"owners_count":22065641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anyscale","chatgpt-api","claude-3-sonnet","deepgram","elevenlabs","fastapi","gpt-4o","llama3","llm","mistral","openai","perplexity-api","polly","telephony","twilio","voice-assistant","websocket-chat","websockets","whisper","xtts"],"created_at":"2024-08-27T19:01:25.908Z","updated_at":"2025-05-15T19:06:31.518Z","avatar_url":"https://github.com/voxos-ai.png","language":"Python","funding_links":["https://api.xpaycheckout.com/link/TO8pQciS"],"categories":["Python"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cp align=\"center\"\u003e\u003cb\u003eEnd-to-end open-source voice agents platform\u003c/b\u003e: Quickly build voice firsts conversational assistants through a json. \u003c/p\u003e\n\u003c/p\u003e\n\n\u003ch4 align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/yDfcqreByj\"\u003eDiscord\u003c/a\u003e |\n  \u003ca href=\"https://docs.bolna.dev\"\u003eDocs\u003c/a\u003e |\n  \u003ca href=\"https://bolna.dev\"\u003eWebsite\u003c/a\u003e\n\u003c/h4\u003e\n\n\u003ch4 align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/yDfcqreByj\"\u003e\n      \u003cimg src=\"https://img.shields.io/static/v1?label=Chat%20on\u0026message=Discord\u0026color=blue\u0026logo=Discord\u0026style=flat-square\" alt=\"Discord\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/bolna-ai/bolna/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"Bolna is released under the MIT license.\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/bolna-ai/bolna/blob/main/CONTRIBUTING.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/PRs-Welcome-brightgreen\" alt=\"PRs welcome!\" /\u003e\n  \u003c/a\u003e\n\u003c/h4\u003e\n\n\n## Introduction\n\n**[Bolna](https://bolna.dev)** is the end-to-end open source production ready framework for quickly building LLM based voice driven conversational applications.\n\n\n## Demo\nhttps://github.com/bolna-ai/bolna/assets/1313096/2237f64f-1c5b-4723-b7e7-d11466e9b226\n\n\n\n## Components\nBolna helps you create AI Voice Agents which can be instructed to do tasks beginning with:\n\n1. Initiating a phone call using telephony providers like `Twilio`, `Plivo`, `Exotel`, etc.\n2. Transcribing the conversations using `Deepgram`, etc.\n3. Using LLMs like `OpenAI`, `Llama`, `Cohere`, `Mistral`,  etc to handle conversations\n4. Synthesizing LLM responses back to telephony using `AWS Polly`, `XTTS`, `ElevenLabs`, `Deepgram` etc.\n5. Instructing the Agent to perform tasks like sending emails, text messages, booking calendar after the conversation has ended\n\nRefer to the [docs](https://docs.bolna.dev/providers) for a deepdive into all supported providers.\n\n\n## Local example setup\nA basic local setup includes usage of [Twilio](local_setup/telephony_server/twilio_api_server.py) or [Plivo](local_setup/telephony_server/plivo_api_server.py) for telephony. We have dockerized the setup in `local_setup/`. One will need to populate an environment `.env` file from `.env.sample`.\n\nThe setup consists of four containers:\n\n1. Telephony web server:\n   * Choosing Twilio: for initiating the calls one will need to set up a [Twilio account](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account)\n   * Choosing Plivo: for initiating the calls one will need to set up a [Plivo account](https://www.plivo.com/)\n2. Bolna server: for creating and handling agents \n3. `ngrok`: for tunneling. One will need to add the `authtoken` to `ngrok-config.yml`\n4. `redis`: for persisting agents \u0026 prompt data\n\nUse docker to build the images using `.env` file as the environment file and run them locally\n1. `docker-compose build --no-cache \u003ctwilio-app | plivo-app\u003e`: rebuild images\n2. `docker-compose up \u003ctwilio-app | plivo-app\u003e`: run the build images\n\nOnce the docker containers are up, you can now start to create your agents and instruct them to initiate calls.\n\n\n\n## Creating your agent and invoking calls\nOnce you have the above docker setup and running, you can create agents and initiate calls.\n1. Use the below payload to create an Agent via `http://localhost:5001/agent`\n\n\u003cdetails\u003e\n\u003csummary\u003eAgent Payload\u003c/summary\u003e\u003cbr\u003e\n\n```yaml\n{\n    \"agent_config\": {\n        \"agent_name\": \"Alfred\",\n        \"agent_type\": \"other\",\n        \"agent_welcome_message\": \"Welcome\",\n        \"tasks\": [\n            {\n                \"task_type\": \"conversation\",\n                \"toolchain\": {\n                    \"execution\": \"parallel\",\n                    \"pipelines\": [\n                        [\n                            \"transcriber\",\n                            \"llm\",\n                            \"synthesizer\"\n                        ]\n                    ]\n                },\n                \"tools_config\": {\n                    \"input\": {\n                        \"format\": \"pcm\",\n                        \"provider\": \"twilio\"\n                    },\n                    \"llm_agent\": {\n                        \"agent_flow_type\": \"streaming\",\n                        \"provider\": \"openai\",\n                        \"request_json\": true,\n                        \"model\": \"gpt-3.5-turbo-16k\",\n                        \"use_fallback\": true\n                    },\n                    \"output\": {\n                        \"format\": \"pcm\",\n                        \"provider\": \"twilio\"\n                    },\n                    \"synthesizer\": {\n                        \"audio_format\": \"wav\",\n                        \"provider\": \"elevenlabs\",\n                        \"stream\": true,\n                        \"provider_config\": {\n                            \"voice\": \"Meera - high quality, emotive\",\n                            \"model\": \"eleven_turbo_v2_5\",\n                            \"voice_id\": \"TTa58Hl9lmhnQEvhp1WM\"\n                        },\n                        \"buffer_size\": 100.0\n                    },\n                    \"transcriber\": {\n                        \"encoding\": \"linear16\",\n                        \"language\": \"en\",\n                        \"provider\": \"deepgram\",\n                        \"stream\": true\n                    }\n                },\n                \"task_config\": {\n                    \"hangup_after_silence\": 30.0\n                }\n            }\n        ]\n    },\n    \"agent_prompts\": {\n        \"task_1\": {\n            \"system_prompt\": \"Ask if they are coming for party tonight\"\n        }\n    }\n}\n```\n\u003c/details\u003e\n\n2. The response of the previous API will return a uuid as the `agent_id`. Use this `agent_id` to initiate a call via the telephony server running on `8001` port (for Twilio) or `8002` port (for Plivo) at `http://localhost:8001/call`\n\n\u003cdetails\u003e\n\u003csummary\u003eCall Payload\u003c/summary\u003e\u003cbr\u003e\n\n```yaml\n{\n    \"agent_id\": \"4c19700b-227c-4c2d-8bgf-42dfe4b240fc\",\n    \"recipient_phone_number\": \"+19876543210\",\n}\n```\n\u003c/details\u003e\n\n\n## Using your own providers\nYou can populate the `.env` file to use your own keys for providers.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eASR Providers\u003c/summary\u003e\u003cbr\u003e\nThese are the current supported ASRs Providers:\n\n| Provider     | Environment variable to be added in `.env` file |\n|--------------|-------------------------------------------------|\n| Deepgram     | `DEEPGRAM_AUTH_TOKEN`                           |\n\n\u003c/details\u003e\n\u0026nbsp;\u003cbr\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLLM Providers\u003c/summary\u003e\u003cbr\u003e\nBolna uses LiteLLM package to support multiple LLM integrations.\n\nThese are the current supported LLM Provider Family:\nhttps://github.com/bolna-ai/bolna/blob/477e08d6800dbf02931abeeea883d78451b7d7e2/bolna/providers.py#L29-L44\n\nFor LiteLLM based LLMs, add either of the following to the `.env` file depending on your use-case:\u003cbr\u003e\u003cbr\u003e\n`LITELLM_MODEL_API_KEY`: API Key of the LLM\u003cbr\u003e\n`LITELLM_MODEL_API_BASE`: URL of the hosted LLM\u003cbr\u003e\n`LITELLM_MODEL_API_VERSION`: API VERSION for LLMs like Azure\n\nFor LLMs hosted via VLLM, add the following to the `.env` file:\u003cbr\u003e\n`VLLM_SERVER_BASE_URL`: URL of the hosted LLM using VLLM\n\n\u003c/details\u003e\n\u0026nbsp;\u003cbr\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eTTS Providers\u003c/summary\u003e\u003cbr\u003e\nThese are the current supported TTS Providers:\nhttps://github.com/bolna-ai/bolna/blob/c8a0d1428793d4df29133119e354bc2f85a7ca76/bolna/providers.py#L7-L14\n\n| Provider   | Environment variable to be added in `.env` file  |\n|------------|--------------------------------------------------|\n| AWS Polly  | Accessed from system wide credentials via ~/.aws |\n| Elevenlabs | `ELEVENLABS_API_KEY`                             |\n| OpenAI     | `OPENAI_API_KEY`                                 |\n| Deepgram   | `DEEPGRAM_AUTH_TOKEN`                            |\n\n\u003c/details\u003e\n\u0026nbsp;\u003cbr\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eTelephony Providers\u003c/summary\u003e\u003cbr\u003e\nThese are the current supported Telephony Providers:\n\n| Provider | Environment variable to be added in `.env` file                                                                                                                    |\n|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Twilio   | `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER`|\n| Plivo    | `PLIVO_AUTH_ID`, `PLIVO_AUTH_TOKEN`, `PLIVO_PHONE_NUMBER`|\n\n\u003c/details\u003e\n\n\n## Extending with other Telephony Providers\nIn case you wish to extend and add some other Telephony like Vonage, Telnyx, etc. following the guidelines below:\n1. Make sure bi-directional streaming is supported by the Telephony provider\n2. Add the telephony-specific input handler file in [input_handlers/telephony_providers](https://github.com/bolna-ai/bolna/tree/master/bolna/input_handlers/telephony_providers) writing custom functions extending from the [telephony.py](https://github.com/bolna-ai/bolna/blob/master/bolna/input_handlers/telephony.py) class\n   1. This file will mainly contain how different types of event packets are being ingested from the telephony provider\n3. Add telephony-specific output handler file in [output_handlers/telephony_providers](https://github.com/bolna-ai/bolna/tree/master/bolna/output_handlers/telephony_providers) writing custom functions extending from the [telephony.py](https://github.com/bolna-ai/bolna/blob/master/bolna/output_handlers/telephony.py) class\n   1. This mainly concerns converting audio from the synthesizer class to a supported audio format and streaming it over the websocket provided by the telephony provider\n4. Lastly, you'll have to write a dedicated server like the example [twilio_api_server.py](https://github.com/bolna-ai/bolna/blob/master/local_setup/telephony_server/twilio_api_server.py) provided in [local_setup](https://github.com/bolna-ai/bolna/blob/master/local_setup/telephony_server) to initiate calls over websockets.\n\n## Open-source v/s Paid\nThough the repository is completely open source, you can connect with us if interested in managed hosted offerings or more customized solutions.\n\n\u003ca href=\"https://calendly.com/bolna/30min\"\u003e\u003cimg alt=\"Schedule a meeting\" src=\"https://cdn.cookielaw.org/logos/122ecfc3-4694-42f1-863f-2db42d1b1e68/0bcbbcf4-9b83-4684-ba59-bc913c0d5905/c21bea90-f4f1-43d1-8118-8938bbb27a9d/logo.png\" /\u003e\u003c/a\u003e\n\n\n## Contributing\nWe love all types of contributions: whether big or small helping in improving this community resource.\n\n1. There are a number of [open issues present](https://github.com/bolna-ai/bolna/issues) which can be good ones to start with\n2. If you have suggestions for enhancements, wish to contribute a simple fix such as correcting a typo, or want to address an apparent bug, please feel free to initiate a new issue or submit a pull request\n2. If you're contemplating a larger change or addition to this repository, be it in terms of its structure or the features, kindly begin by creating a new issue [open a new issue :octocat:](https://github.com/bolna-ai/bolna/issues/new) and outline your proposed changes. This will allow us to engage in a discussion before you dedicate a significant amount of time or effort. Your cooperation and understanding are appreciated\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxos-ai%2Fbolna","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoxos-ai%2Fbolna","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoxos-ai%2Fbolna/lists"}