PBot Overview

This document will provide a high level overview of PBot. The project is lightweight and fairly simple but good documentation is the first barrier to entry for any open source project adoption.

Services

PBot is a dockerized application with multiple running services. Beyond those related to Redis, there are two main services that make up PBot:

  • Transceiver Service

  • Bot Service

  • (Admin Frontend Service OTW)

_images/services.png

See the project-wide docker-compose.yml file.


Transceiver Service

A lighweight service meant to transmit responses to and receive messages from Discord. This service is event driven and based on Discord.py which in turn is based on asyncio.

Unless you want to modify the models stored in Redis, you likely wont need to delve into the transceiver service.

See Transceiver Service for details.


Bot Service

The bot proper.

The bot service constantly looks for channels with recent message activity. If new unread messages are found and the channel is enabled the recent message history for that channel is passed through each middleware layer, before final clean up tasks are run like marking the messages as read.

The most likely starting point for any development is the middleware run by the bot service.

See Bot Service for details.


Chatbot Middleware

This is where all the heavy lifting is done. The rest of of this project is just meant to make this part easy and fun! ☺

Middleware can be thought of as a stack of layers that our message history will be passed through. Any given layer may manipulate the message history and/or otherwise act on it.

_images/middleware.png

Each layer on the stack is just a class that inherits from the class pbot.middleware.base.Middleware. Creating your own middleware layer only requires that you implement a single method, handle_messages. This method must accept a list of messages and return a list. What your middleware otherwise does, is entirely up to you.

Note

The order middleware is loaded matters.

Warning

When authoring middleware and mutating the message history, consider clean up like marking removed messages as read.



Project Structure

Outlined below are the key files and folders of the project.

  • pbot/ ← Project root.
    • config/ ← Project-wide configurations.

      • .env ← Shared environment variables & secrets.

      • docker-compose.yml

    • docs/

    • services/ ← Service containers.
      • bot/
        • src/
          • pbot/

            • [service source code]

          • app.py

          • requirements.txt

        • Dockerfile

      • transceiver/
        • src/
          • transceiver/

            • [service source code]

          • app.py

          • requirements.txt

        • Dockerfile

    • requirements.txt

    • tasks.py ← Local development tasks.

Project To Do

TODO.md

# TODO

- Find open source fork of redis or replace it outright (rugpull).
- Tighter default expiry limits on messages in Redis.
- Better pattern for models.
- Discord rate limit--don't let bots get themselves banned.
- OpenAI middleware:rate limit & usage cap.
- Port over Midjourney integration.
- Scheduled/recurring tasks.