`oobabot`

oobabot is a Discord bot which talks to Large Language Model AIs (like Llama, Mistral, ChatGPT, etc...), using just about any API-enabled backend.

It even supports non-local solutions such as Openrouter, Cohere, OpenAI, etc.

Updated! Use --generate-config and update your configs! If you want to migrate your existing config, specify your config file as well: -c config.yml --generate-config

Installation and Quick Start!

Requires python 3.8+

See INSTALL.md for detailed installation instructions.

Install LLM backend with an OpenAI-compatible API.
- Optionally, skip this step and run via a cloud provider!
Create a Discord bot account, invite it to your server, and note its authentication token.
Install oobabot (see INSTALL.md)

Generate a configuration file

$ oobabot --generate-config > config.yml

Edit config.yml with you favorite text editor and fill in all the cool parts.
Generate an invite link and click/copy it into your browser.
```
$ oobabot --invite-url -c config.yml
```
Finally, run the bot!
```
$ oobabot -c config.yml
```
or if you installed it with Poetry:
```
$ poetry run oobabot
```

Features

`oobabot`	How that's awesome
User-supplied persona	You supply the persona on how would like the bot to behave
Multiple conversations	Can track multiple conversational threads, and reply to each in a contextually appropriate way
Wakewords	Can monitor all channels in a server for one or more wakewords or @-mentions
Private conversations	Can chat with you 1:1 in a DM
Good Discord hygiene	Splits messages into independent sentences, pings the author in the first one
Low-latency	Streams the reply live, sentence by sentence, or even by small groups of tokens. Provides lower latency, especially on longer responses.
Stats	Track token generation speed, latency, failures and usage
Easy networking	Connects to discord from your machine using websockets, so no need to expose a server to the internet
Stable Diffusion	Optional image generation with AUTOMATIC1111
Slash commands	Did your bot get confused? `/lobotomize` it!
OpenAI API support	Roughly supports OpenAI-compatible API endpoints as well as the Cohere API (Command R+)
Vision API support	Roughly supports GPT Vision API (tested with llama-cpp-python API and LocalAI)

You should now be able to run oobabot from wherever pip installed it. If you're on windows, you should use python3 -m oobabot (args here)

There are a LOT of settings in the config.yml, and it can be tough to figure out what works best. There is a somewhat populated example config here for you to inspect and get familiar with. This config is not complete and has no Discord token, so don't try to run the bot with it. Generate a configuration file first, then fill out what you need.

Optional settings

wakewords

One or more words that the bot will look for. It will reply to any message which contains one of these words, in any channel.

Persona: the fun setting

persona

This is a short few sentences describing the role your bot should act as. For instance, this is what you might use for a cat-bot, whose name is "Rosie".

Here is some background information about Rosie:
- You are Rosie
- You are a cat
- Rosie is a female cat
- Rosie is owned by Chris, whose nickname is xxxxxxx
- Rosie loves Chris more than anything
- You are 9 years old
- You enjoy laying on laps and murder
- Your personality is both witty and profane
- The people in this chat room are your friends

Persona may be set from the command line with the --persona argument, or within the config.yml.

Alternatively, oobabot supports loading Tavern-style JSON character cards!

# Path to a file containing a persona.  This can be just a single string, a json file in the common "tavern" formats, or a yaml file in the Oobabooga format. With a single string, the persona will be set to that string. Otherwise, the ai_name and persona will be overwritten with the values in the file. Also, the wakewords will be extended to include the character's own name.
#   default:
persona_file:

Then, run it

You should see something like this if everything worked:

Interacting with `oobabot`

By default, oobabot will listen for three types of messages in the servers it's connected to:

Any message in which oobabot's account is @-mentioned
Replies to oobabot's messages
Any direct message
Any message containing a provided wakeword (see Optional Settings)

Also, the bot has a random chance of sending follow-up messages within the same channel if others reply within 120 seconds of its last post. This "random chance" is configurable via the config.yml:

# Time vs. response chance - calibration table List of tuples with time in seconds and response chance as float between 0-1
#   default: ['(180.0, 0.99)', '(300.0, 0.7)', '(600.0, 0.5)']
time_vs_response_chance:

Here, you can see that NEW messages within 3 minutes of the bot's last reply will have a 99% chance of response.

Between 3-5 minutes, the default chance drops to 70%
Between 5-10 minutes, the default chance drops to 50%

Feel free to configure this to suit your needs!

Reaction controls

As of 0.3.0, the bot now supports reaction controls:

React to one of the bot's messages with ❌ to delete it.
React to one of the bot's messages with 🔁 to regenerate it.
React to one of the bot's messages with ⏪ to hide that message and all messages before it from the bot's chat history.

After the action is complete, the reaction will be automatically removed. Note that the bot cannot remove reactions itself in DMs and Group DMs. This is by design due to Discord channel types and their respective permissions. You must remove the reaction yourself if you are in a DM with the bot.

Slash Commands

As of 0.3.0, the bot now supports the following slash commands:

`/command`	What it does
`/lobotomize`	Make the bot forget everything in the channel before the command is run
`/say "message"`	Make the bot post the provided message
`/edit "message"`	Make the bot edit its most recent message with the provided message
`/stop`	Make the bot abort the currently generating message and post what it has so far
`/poke`	Prompt the bot to reply to the last message

Oobabot doesn't add any restrictions on who can run these commands, but luckily Discord does! You can find this inside Discord by visiting "Server Settings" -> Integrations -> Bots and Apps -> hit the icon which looks like [/] next to your bot

If you're running on a large server, you may want to restrict who can run these commands. I suggest creating a new role, and only allowing that role to run the commands.

Stable Diffusion via AUTOMATIC1111

stable-diffusion-url

This is the URL to a server running AUTOMATIC1111/stable-diffusion-webui

With it, users can ask oobabot to generate images and post the results to the channel. The user who made the original request can choose to regenerate the image as they like. If they either don't find one they like, or don't do anything within 3 minutes, the image will be removed.

Currently, detection of photo requests is very crude, and is only looking for messages which match this regex:
```
image_words = ["draw", "sketch", "paint", "make", "generate", "post", "upload"]
image_patterns = [
  re.compile(
      r"^.*\b" + image_word
      + r"\b\s*((as?|of|the|with)\b\s*)*:?"
      + r"([\w\s,;:<>`~@#%&_=\$\^\*\-\+\[\]\{\}\"\']+)"
      + r".*$",
      re.IGNORECASE + re.MULTILINE,
  )
  for image_word in self.image_words
]
```
The image words are configurable in the settings file. As the defaults are rather permissive, experiment with what works best for you in terms of false positives.

Note that depending on the checkpoint loaded in Stable Diffusion, it may not be appropriate for your server's community. I suggest reviewing Discord's Terms of Service and Community Guidelines before deciding what checkpoint to run.

oobabot supports two different negative prompts, depending on whether the channel is marked as "Age-Restricted" or not. This is to allow for more explicit content in channels which are marked as such. While the negative prompt will discourage Stable Diffusion from generating an image which matches the prompt, but is not foolproof.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for more information.

xBelladonna/oobabot

oobabot