# BanterBot
BanterBot is a user-friendly chatbot application that leverages OpenAI models for generating context-aware responses, Azure Neural Voices for text-to-speech synthesis, and Azure speech-to-text recognition. The package offers a comprehensive toolkit for building chatbot applications with an intuitive interface and a suite of utilities.
## Features
* Utilizes OpenAI models to generate context-aware responses
* Leverages Azure Neural Voices for premium text-to-speech synthesis
* Offers a wide range of output formats, multilingual voices, and speaking styles
* Allows real-time monitoring of the chatbot's responses
* Supports asynchronous speech-to-text microphone input
* Includes an abstract base class for creating custom frontends for the BanterBot application
* Features a tkinter-based frontend implementation
* Automatically selects an appropriate emotion or tone based on the conversation context
## Requirements
Three environment variables are required for full functionality:
* `OPENAI_API_KEY`: A valid OpenAI API key
* `AZURE_SPEECH_KEY`: A valid Azure Cognitive Services Speech API key for text-to-speech and speech-to-text functionality
* `AZURE_SPEECH_REGION`: The region associated with your Azure Cognitive Services Speech API key
## Components
### TKInterface
A graphical user interface (GUI) establishes a multiplayer conversation environment where up to nine users can interact with the chatbot simultaneously. The GUI includes a conversation history area and user panels with 'Listen' buttons to process user input. It also supports key bindings for user convenience.
### OpenAIService
A class responsible for managing interactions with the OpenAI ChatCompletion API. It offers functionality to generate responses from the API based on input messages. It supports generating responses in their entirety or as a stream of response blocks.
### SpeechSynthesisService
A class that handles text-to-speech synthesis using Azure's Cognitive Services. It supports a wide range of output formats, voices, and speaking styles. The synthesized speech can be interrupted, and the progress can be monitored in real-time.
### SpeechRecognitionService
A class that provides an interface to convert spoken language into written text using Azure Cognitive Services. It allows continuous speech recognition and provides real-time results as sentences are recognized.
## Installation
### Important Note
BanterBot requires several spaCy language models to run, and will automatically download them on first-time initialization, if they are missing or incompatible -- this process can sometimes take a while.
### Pip (Recommended)
BanterBot can be installed or updated using the Python Package Index (PyPi):
```bash
python -m pip install --upgrade banterbot
```
### Manual
To install BanterBot, simply clone the repository and install the required dependencies:
```bash
git clone https://github.com/gabrielscabrera/banterbot.git
cd banterbot
python -m pip install .
```
## Usage
### Launch with Command Line
Start BanterBot with an enhanced graphical user interface by running the command `banterbot` in your terminal. This GUI allows multiple users to interact with the bot, each with a dedicated button for speech input and a display for responses.
`--prompt`: Set a system prompt at the beginning of the conversation (e.g., `--prompt "You are Grendel the Quiz Troll, a charismatic troll who loves to host quiz shows."`).
`--model`: Choose the OpenAI model for conversation generation. Defaults to GPT-4, but other versions can be selected if specified in the code.
`--voice`: Select a Microsoft Azure Cognitive Services text-to-speech voice. The default is "Aria," but other voices can be specified if available.
`--debug`: Enable debug mode to display additional information in the terminal for troubleshooting.
`--greet`: Have the bot greet the user upon startup.
`--name`: Assign a name to the assistant for aesthetic purposes. This does not inform the bot itself; to provide the bot with information, use the `--prompt` flag.
Here is an example:
```bash
banterbot --greet --model gpt-4-turbo --voice davis --prompt "You are Grondle the Quiz Troll, a charismatic troll who loves to host quiz shows." --name Grondle
```
Additionally, you can use `banterbot character` to select a pre-loaded character to interact with. For example:
```bash
banterbot character therapist
```
Will start a conversation with Grendel the Therapy Troll. To list all available characters, run:
```bash
banterbot character -h
```
You can also use `banterbot voice-search` to search through all the available voices. For example:
```bash
banterbot voice-search --language en fr
```
Will list all English (en) and French (fr) voice models. Run `banterbot voice-search -h` for more information.
### Launch with a Python script
To use BanterBot in a script, create an instance of the `TKInterface` class and call the `run` method:
```python
from banterbot import AzureNeuralVoiceManager, OpenAIModelManager, TKInterface
model = OpenAIModelManager.load("gpt-4o")
voice = AzureNeuralVoiceManager.load("Davis")
assistant_name = "Grendel"
# Optional system prompt to set up a custom character prior to initializing BanterBot.
system = "You are Grendel the Quiz Troll, a charismatic troll who loves to host quiz shows."
# The four arguments `model`, `voice`, `system`, and `assistant_name` are optional.
interface = TKInterface(model=model, voice=voice, system=system, assistant_name=assistant_name)
# Setting `greet` to True instructs BanterBot to initiate the conversation. Otherwise, the user must initiate.
interface.run(greet=True)
```
## Chat Logs
Chat logs are saved in the `$HOME/Documents/BanterBot/Conversations/` directory as individual `.txt` files.
## Documentation
For more complete documentation, please refer to the [BanterBot Docs](https://gabrielscabrera.github.io/BanterBot/).
Raw data
{
"_id": null,
"home_page": "https://github.com/GabrielSCabrera/BanterBot",
"name": "BanterBot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "tkinter, tk, gpt, gui, windows, linux, cross-platform, chatgpt, text-to-speech, speech-to-text, tts, stt, chatbot, openai, interactive",
"author": "Gabriel S. Cabrera",
"author_email": "gabriel.sigurd.cabrera@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/29/81/100090b9660a3e29576e1243a6a514cc4768f45e089f82d0161bd2276d1c/BanterBot-0.0.16.tar.gz",
"platform": null,
"description": "# BanterBot\r\n\r\nBanterBot is a user-friendly chatbot application that leverages OpenAI models for generating context-aware responses, Azure Neural Voices for text-to-speech synthesis, and Azure speech-to-text recognition. The package offers a comprehensive toolkit for building chatbot applications with an intuitive interface and a suite of utilities.\r\n\r\n## Features\r\n\r\n* Utilizes OpenAI models to generate context-aware responses\r\n* Leverages Azure Neural Voices for premium text-to-speech synthesis\r\n* Offers a wide range of output formats, multilingual voices, and speaking styles\r\n* Allows real-time monitoring of the chatbot's responses\r\n* Supports asynchronous speech-to-text microphone input\r\n* Includes an abstract base class for creating custom frontends for the BanterBot application\r\n* Features a tkinter-based frontend implementation\r\n* Automatically selects an appropriate emotion or tone based on the conversation context\r\n\r\n## Requirements\r\n\r\nThree environment variables are required for full functionality:\r\n\r\n* `OPENAI_API_KEY`: A valid OpenAI API key\r\n* `AZURE_SPEECH_KEY`: A valid Azure Cognitive Services Speech API key for text-to-speech and speech-to-text functionality\r\n* `AZURE_SPEECH_REGION`: The region associated with your Azure Cognitive Services Speech API key\r\n\r\n## Components\r\n\r\n### TKInterface\r\n\r\nA graphical user interface (GUI) establishes a multiplayer conversation environment where up to nine users can interact with the chatbot simultaneously. The GUI includes a conversation history area and user panels with 'Listen' buttons to process user input. It also supports key bindings for user convenience.\r\n\r\n### OpenAIService\r\n\r\nA class responsible for managing interactions with the OpenAI ChatCompletion API. It offers functionality to generate responses from the API based on input messages. It supports generating responses in their entirety or as a stream of response blocks.\r\n\r\n### SpeechSynthesisService\r\n\r\nA class that handles text-to-speech synthesis using Azure's Cognitive Services. It supports a wide range of output formats, voices, and speaking styles. The synthesized speech can be interrupted, and the progress can be monitored in real-time.\r\n\r\n### SpeechRecognitionService\r\nA class that provides an interface to convert spoken language into written text using Azure Cognitive Services. It allows continuous speech recognition and provides real-time results as sentences are recognized.\r\n\r\n## Installation\r\n\r\n### Important Note\r\n\r\nBanterBot requires several spaCy language models to run, and will automatically download them on first-time initialization, if they are missing or incompatible -- this process can sometimes take a while.\r\n\r\n### Pip (Recommended)\r\n\r\nBanterBot can be installed or updated using the Python Package Index (PyPi):\r\n\r\n```bash\r\npython -m pip install --upgrade banterbot\r\n```\r\n\r\n### Manual\r\n\r\nTo install BanterBot, simply clone the repository and install the required dependencies:\r\n\r\n```bash\r\ngit clone https://github.com/gabrielscabrera/banterbot.git\r\ncd banterbot\r\npython -m pip install .\r\n```\r\n\r\n## Usage\r\n\r\n### Launch with Command Line\r\n\r\nStart BanterBot with an enhanced graphical user interface by running the command `banterbot` in your terminal. This GUI allows multiple users to interact with the bot, each with a dedicated button for speech input and a display for responses.\r\n\r\n`--prompt`: Set a system prompt at the beginning of the conversation (e.g., `--prompt \"You are Grendel the Quiz Troll, a charismatic troll who loves to host quiz shows.\"`).\r\n\r\n`--model`: Choose the OpenAI model for conversation generation. Defaults to GPT-4, but other versions can be selected if specified in the code.\r\n\r\n`--voice`: Select a Microsoft Azure Cognitive Services text-to-speech voice. The default is \"Aria,\" but other voices can be specified if available.\r\n\r\n`--debug`: Enable debug mode to display additional information in the terminal for troubleshooting.\r\n\r\n`--greet`: Have the bot greet the user upon startup.\r\n\r\n`--name`: Assign a name to the assistant for aesthetic purposes. This does not inform the bot itself; to provide the bot with information, use the `--prompt` flag.\r\n\r\nHere is an example:\r\n\r\n```bash\r\nbanterbot --greet --model gpt-4-turbo --voice davis --prompt \"You are Grondle the Quiz Troll, a charismatic troll who loves to host quiz shows.\" --name Grondle\r\n```\r\n\r\nAdditionally, you can use `banterbot character` to select a pre-loaded character to interact with. For example:\r\n\r\n```bash\r\nbanterbot character therapist\r\n```\r\n\r\nWill start a conversation with Grendel the Therapy Troll. To list all available characters, run:\r\n\r\n```bash\r\nbanterbot character -h\r\n```\r\n\r\nYou can also use `banterbot voice-search` to search through all the available voices. For example:\r\n\r\n```bash\r\nbanterbot voice-search --language en fr\r\n```\r\n\r\nWill list all English (en) and French (fr) voice models. Run `banterbot voice-search -h` for more information.\r\n\r\n### Launch with a Python script\r\n\r\nTo use BanterBot in a script, create an instance of the `TKInterface` class and call the `run` method:\r\n\r\n```python\r\nfrom banterbot import AzureNeuralVoiceManager, OpenAIModelManager, TKInterface\r\n\r\nmodel = OpenAIModelManager.load(\"gpt-4o\")\r\nvoice = AzureNeuralVoiceManager.load(\"Davis\")\r\nassistant_name = \"Grendel\"\r\n\r\n# Optional system prompt to set up a custom character prior to initializing BanterBot.\r\nsystem = \"You are Grendel the Quiz Troll, a charismatic troll who loves to host quiz shows.\"\r\n\r\n# The four arguments `model`, `voice`, `system`, and `assistant_name` are optional.\r\ninterface = TKInterface(model=model, voice=voice, system=system, assistant_name=assistant_name)\r\n\r\n# Setting `greet` to True instructs BanterBot to initiate the conversation. Otherwise, the user must initiate.\r\ninterface.run(greet=True)\r\n```\r\n\r\n## Chat Logs\r\n\r\nChat logs are saved in the `$HOME/Documents/BanterBot/Conversations/` directory as individual `.txt` files.\r\n\r\n## Documentation\r\n\r\nFor more complete documentation, please refer to the [BanterBot Docs](https://gabrielscabrera.github.io/BanterBot/).\r\n",
"bugtrack_url": null,
"license": null,
"summary": "BanterBot: An OpenAI ChatGPT-powered chatbot with Azure Neural Voices. Supports speech-to-text and text-to-speech interactions with emotional tone selection. Features real-time monitoring and Tkinter frontend.",
"version": "0.0.16",
"project_urls": {
"Download": "https://github.com/GabrielSCabrera/BanterBot/releases/download/v0.0.16-alpha/BanterBot-0.0.16.tar.gz",
"Homepage": "https://github.com/GabrielSCabrera/BanterBot"
},
"split_keywords": [
"tkinter",
" tk",
" gpt",
" gui",
" windows",
" linux",
" cross-platform",
" chatgpt",
" text-to-speech",
" speech-to-text",
" tts",
" stt",
" chatbot",
" openai",
" interactive"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3dfb44c3d8529b21cc408b9529f659273f27a52cbe10f124d87963a1fe2e5786",
"md5": "5c36540090d6c5c42c161b48107e2f12",
"sha256": "886ca42f153b6a825e0db152120e7d5dc7f6da82824941e91ca7918d2a5cdfe0"
},
"downloads": -1,
"filename": "BanterBot-0.0.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c36540090d6c5c42c161b48107e2f12",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 89054,
"upload_time": "2024-05-14T18:16:02",
"upload_time_iso_8601": "2024-05-14T18:16:02.338953Z",
"url": "https://files.pythonhosted.org/packages/3d/fb/44c3d8529b21cc408b9529f659273f27a52cbe10f124d87963a1fe2e5786/BanterBot-0.0.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2981100090b9660a3e29576e1243a6a514cc4768f45e089f82d0161bd2276d1c",
"md5": "9a9092cce6ad516c85fa666f29f3ce25",
"sha256": "3b61ab79c4664e060c2eb5540e7677dd66a557fb89ce73410ca7656111041505"
},
"downloads": -1,
"filename": "BanterBot-0.0.16.tar.gz",
"has_sig": false,
"md5_digest": "9a9092cce6ad516c85fa666f29f3ce25",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 67846,
"upload_time": "2024-05-14T18:16:04",
"upload_time_iso_8601": "2024-05-14T18:16:04.180555Z",
"url": "https://files.pythonhosted.org/packages/29/81/100090b9660a3e29576e1243a6a514cc4768f45e089f82d0161bd2276d1c/BanterBot-0.0.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-14 18:16:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GabrielSCabrera",
"github_project": "BanterBot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "banterbot"
}
JSON
