mrhedmad/milton

Home of Milton Lab Assistant - the Discord Bot for laboratories.

The Milton Lab Assistant

Home of Milton Lab Assistant - the Discord Bot.

There is only me, and you, and an eternity of doubt.

— Milton

About

This is a Discord bot mainly aimed at managing a research laboratory Discord Server. It has specific features designed with research and a laboratory in mind.

The bot uses a local SQLite database to store its data.

Deploy your own instance

To install and run milton, follow these instructions:

1. Install python 3.10 or later and git. I assume that python points to the Python 3.11 interpreter;
2. Optionally, but highly advised, make a virtual environment and enter it with python -m venv env followed by source env/bin/activate.
3. Install the bot with pip install git+https://github.com/MrHedmad/Milton.git@release.
   • Optionally, you can remove the @release to install the latest dev branch.
4. Configure the bot, such as adding your bot token (see below).
5. Run the bot by executing milton (while in the env, if you made one).

To re-run the bot after you install it, run milton again while in the virtual environment.

Configuration

Milton looks in $HOME/.config/milton/milton.toml to find its configuration. The configuration is a TOML file with this possible fields:

[bot]
token = # The bot's token
pagination_timeout = 300 # Time it takes to time out pagination, in seconds
test_server_id = 12345678900000 # The ID of the test server, if any.
# A list of the names of the extensions to load at startup.
startup_extensions = [
    "meta", "toys", "birthday", "math_render", "rss", "pdf_render"
]

[database]
path = "~/.milton/database.sqlite" # Where to store and look for the database file

[logs]
path = "~/.milton/logs/mla.log" # Where to store and look for the logs
# Logging levels (0: all, 10: DEBUG, 20: INFO, 30: WARNING, 40: ERROR, 50: CRITICAL)
file_level = 10 # logging level of messages saved to file.
stdout_level = 30 # logging level of messages sent to stdout.

[prefixes]
guild = "!!" # Prefix to use when invoking the bot in a guild (server).

[emojis]
# You usually do not change these. They are the emojis used when paginating.
trash = "\u274c"
next = "\u25b6"
back = "\u25c0"
last = "\u23e9"
first = "\u23ea"
stop = "\u23f9"

[birthday] # Config of the birthday cog
when = 10 # Time (in hours) to announce new birthdays. Uses local timezone.

Following the TOML convention, just remove a field if you'd like to use its default value.

One config you must override is the bot > token field, providing your own discord bot token. Milton will not start without a token.

Invite your bot

In the Discord Developers panel you can get a link

Interactive use

When you launch milton, a CLI will appear. Here, you may launch admin commands to manage your milton instance. You can get a list of all commands using help.

Note: Misspelled commands are (lightly) grobbed to what Milton thinks you want. This was mainly implemented since I constanly misspell shutdown.

Contributing to Milton

You can contribute to the bot by adding an extension that does something cool. Extensions should be put in the cogs folder and loaded in the bot.py script. More information on how to correctly write extensions can be found in the discord.py documentation.

I welcome and will review all pull requests.

Setting up for development

To setup for developing Milton, you will need python 3.11 installed. Follow the standard GitHub contributing workflow.

I strongly suggest working in a virtual environment. Install the dev dependencies with pip install -r requirements-dev.txt, then setup pre-commit with pre-commit install.

We follow the black code style and the conventional commits commit message style. The conventional commits standard that I follow is here.

milton's Issues

Add a docker container option to run Milton

Deploying an instance is easy, but sometimes - due to Python versioning and some other external requirements that apparently not everyone has (cough poppler cough) - it can be a pain.

Write a Dockerfile to generate a Docker image, so that deployment is easier.

TODO

• Write a dockerfile;
• Add an auto-deploy-to-dockerhub action on release;
• Write an utility script that pulls the image if needed, mounts the volumes as needed and runs the bot instance;
• Add to the README this possibility (with those cool and super unsafe 'Run wget ... | sh and get started in seconds!' bits)

Add a public github repository browser feature

One often needs to retrieve or inspect a remote repository file. We should add a cog that, for public repositories (private repos need token access, but we cannot store it not in plain text for now, so let's not do that), fuzzy-finds the files and:

• If no files match, say so and provide a link to the repo;
• If one file matches, provide a link and the content (cropped if need be) of the file;
• If multiple file match, provide a list of them with relevant links;

Additionally, it would be nice to implement:

• An optional grep pattern to match the file with;

Tracking

• Core implementation
• Grep support

Announcements cog email providers

Currently, the annoucements cog uses google to send emails. Gmail is not meant to be used to send emails from automated accounts.

The cog should be modified to use a commercial email provider like SendGrid or similar, which provide actual robust APIs to send automatic announcement emails.

On the other hand, the cog could be simply replaced by a mailing-list manager cog, that records who want to be emailed and provides the correct email list that a human can then use to send announcements.

The error handler should be more composable.

The error handler should be more composable. By this I mean using decorators with functions to handle single errors.

It is probably best to move from a cog to a module in the bot's core, and make the loading of the handler mandatory, with listeners in the bot instance itself.

As cogs can handle their own cog-specific errors, adding and removing handlers in the error handler at run time is not necessary.

Support hybrid commands

The slash command stuff by Discord is nice, but since this bot is designed to not be deployed in a very large number of servers, the privileged MessageContent intent can still be requested. For some commands, like:

• Github browsing (See issue #17);
• The "snippet" feature (See issue ?);
• Some admin-only commands in the various cogs (like the 'sudo' announcement commands and the birthday admin commands);

it makes sense to make them text-only (or dual text-slash).

Rebranding

I want Milton to target research organizations, so we have to do some rebranding:

• Change Milton's name to "Milton Lab Assistant";
• Rebrand Milton's logo to something more... pretty?

Prefer .config configuration

Please do not pollute my $HOME with junk. Thanks!

Migrate from YAML to TOML configs

The YAML parsing is way too powerful for the very, very simple things that we need to do.

TOML is very easy to parse, supports comments, and is very easy to write. Since we need to do something simple, let's use something simple to do it.

Add conventional commits specifications

We should begin following the gitmoji specification.

Also, add the tag to the README

Bot only allows a single owner.

Allowing multiple owners should be allowed, as d.py does allow multiple bot owners.

This change should be reflected in the configuration as well as in any custom checks done in milton.utils.checks.

Update documentation

The documentation needs a bit of love:

• Write a better README, and add the all-contributors bot.
• Write an actual CONTRIBUTING.md guide.
• Write a tiny bit of documentation on how to configure the bot.

Perhaps the docs should be moved to their own /docs/ dir, for better future support.

Miscellaneous Housekeeping

Some minor tasks are listed here, which may not require a commit per-se, but they should be addressed nonetheless:

• The paginator might be weird with the new slash command specification;
• Add utilites to access the pkg_resources in an easier way (and as Paths instead of whatever the package.resources module gives out).

Implement reagent catalogue cog

A reagent catalogue is a collection of all the names of the reagents, their location and their quantity that is present in a lab.

A cog that can create, manage and help in browsing such a catalogue would be useful.

The utils.tasks command should be removed

A long time ago I submitted a PR to d.py with a change to the tasks module that allowed tasks to run at specific times each day. The PR was rejected, but a (better) version of it has since been included in the discord.ext.tasks module.

Therefore, the utils.tasks file (with my PR) has since been superseded by the d.py implementation.

We should migrate from the local tasks file to the d.py one.

Extract the core/cogs folder to the core folder

The core/cogs folder adds a lot of visual confusion on where to put actual core cogs that must be loaded and those that can be disabled.

The folder should be removed, and the "core" cogs moved in just "core".

Deprecate useless cogs

Some cogs have run their course: They were implemented at the very start of development mostly to test features out. Since they just add useless commands, they should be removed:

• The roll command in the toys cog;
• The ping command in the meta cog;

The CLI module is terrible

The CLI module (cli.py) should be overhauled.

• There is no support to use ARROW UP and ARROW DOWN to cycle through the CLI history.
• There is not TAB completion support.
• There could be command composition support (such as that provided by discord.py)

A possible solution would be to use an appropriate library such as click or similar, but they would need to be capable of async.

It is best to move the CLI out of the cogs and into the bot itself, and schedule its execution with asyncio.Loop.create_task as the bot starts (run) and stop it as the bot closes (close).

Dependencies for the bot migth not be up-to-date

There might be some dependencies that the bot does not use, or can avoid using (by implementing the functionality in the bot itself).