This code is still very rough but I am trying to make a tool which others could use for their own bots. Someone online said,
A general-purpose template of an ICYMI bot would be most welcome. I’m thinking of deploying more bots myself for topics I’m interested in, but a (relatively) easy way for people to run such bots would be very good, so that more interest communities have them.
… and these notes should give an idea how you could use my code to make your own #icymiBot
Basis
These instructions assume some familiarity with the command-line of your computer system.1 My home set-up is MacOS but it should work on most Unix-like systems.
Matt Hodges has written a good detailed README for his mastodon digest code, on which this bot code is based, and I strongly recommend giving that at least a glance. It goes into more detail on some points which the notes below gloss over.
The code is written in python. You should not need to know python to run the code, but if your experience with python is like mine, it may take a bit of fiddling to get running on your version of python (or one of your versions of python).2
Where does the code come from?
The code is a branch of Matt Hodges’ mastodon-digest code. Matt’s code is not built as a bot – it is intended for personal use to create a single page digest of a particular timeline. I have adapted it so that the same basic algorithm for looking through a large number of posts and deciding which ones are interesting (but have not been interacted with) is used to decide which posts to boost.
Getting the code
Clone the mastodon-digest-bot branch into a directory on your computer. (When you press the green “Code” button on the github page it offers several options how to do this.)
git clone -b bot_basis https://github.com/RichardMN/mastodon_digest.git
Building the code
The code ships with a Makefile. Running it once should get it to install the necessary python libraries to run.
make local
This should at least give you a local environment of python.
Configuration
The bot will not work (to make a digest or do anything else) without editing a file or two.
You will need to give the bot credentials (in the .env file) and you probably want to configure it (in the cfg.yaml file).
The .env file
Copy the .env.example file to .env and make it match the settings for your bot’s account on a mastodon instance.
cp .env.example .env
The .env file comes as follows:
MASTODON_TOKEN=SETME
MASTODON_BASE_URL=SETME
Edit this to replace SETME with the token (from the Preferences->Development pane of your bot’s mastodon account) and with the base url of your mastodon account’s instance (e.g., https://mastodon.social)
It should end up looking something like:
MASTODON_TOKEN=AJDAasdkaj23891d_faqw3d-231SDAZads322DADSnx
MASTODON_BASE_URL=https://ndstm.social
(These are somewhat representative values but won’t work for you.)
The cfg.yaml file
Copy the cfg.yaml.example file to cfg.yaml.
cp cfg.yaml.example cfg.yaml
The cfg.yaml file lets you adjust the detailed settings of your bot, allowing you to fix the options for how the bot runs in a file (instead of having long unwieldy command lines).
Important: Command-line options override settings in the cfg.yaml file. This means that you can set your regular defaults in the cfg.yaml and adjust just a few of them when you run the bot from the command line.
From the defaults, the cfg.yaml file looks like this:
# corresponds to command line argument '-f'
# Expects 'home', 'local' or 'federated', or 'list:id', 'hashtag:tag'
# default: home
timeline: "home"
# corresponds to command line argument '-s'
# Expects ExtendedSimple, ExtendedSimpleWeighted, Simple, SimpleWeighted
scorer: "ExtendedSimpleWeighted"
# corresponds to command line argument '-n'
# From the command line only values up to 24 are possible, but
# in the config file any whole number value should work.
# Default is 12
hours: 12
# corresponds to command line argument '-t'
# Expects lax, normal, strict
threshold: "normal"
# corresponds to command line argument '-o'
# Default: "./render/"
output_dir: "./render/"
# corresponds to command line argument '--theme'
theme: "default"
# output format
# corresponds to command line argument '--output'
# Generate an HTML digest ("html") or run as a bot amplifying toots ("bot")
output_type: "html"
The defaults will operate “safely”, generating an HTML digest page of toots in render/index.html.
- You could adjust the feed so that the bot looks at a different timeline. It could be used to generate a regular digest for the
localtimeline of your instance. - You can choose which scorer is used.
- You can can change the default number of hours back in the feed the bot looks, so that if you run it every 6 hours it only looks back 6 hours (or looks back 8 hours to account for some overlap).
- Though you can set the output to default to
bot, this is not how I use it.
My workflow
I am still adjusting the code for the bot and how it interacts with its feed so I run it manually a few times a day.
![Etching of a hand-cranked hammer from Besson, Jacques, (Mathematician. 1578. Theatrum instrumentorum et machinarum Iacobi Bessoni .. cum Franc. Beroaldi figurarum declaratione de monstratiua [sic]., Lugduni : Apud Barth. Vincentium.](/images/SIL-SIL4-2-57-hand-cranked-hammer-crop.jpg)
Hand cranked hammer from Besson, Jacques, (Mathematician. 1578. Theatrum instrumentorum et machinarum Iacobi Bessoni .. cum Franc. Beroaldi figurarum declaratione de monstratiua [sic]., Lugduni : Apud Barth. Vincentium., courtesy of Smithsonian Libraries and Archives.
First I run the bot to generate an HTML digest, open it in Safari, and copy a version of the HTML digest to a timestamped file. (If nothing else, this helps me keep track of when I last ran the bot.)
The bot will tell you that it is loading a config file, print out the token it is using to access your mastodon instance server (don’t include this in any output you put online), tell you how long it is looking back to create a digest in hours.
.venv/bin/python run.py -n 12 --output html
open render/index.html
cp -p render/index.html render/index-`date "+%Y%m%dh%H%M"`.html
If I don’t see anything too weird, I then re-run the same code
.venv/bin/python run.py -n 12 --output bot
The bot gives the same output, then announces which toots it is boosting, and exits. It does not (yet) keep track of statistics in terms of how many toots it looked at, how many it dropped. (There are development branches which are noisier about their decision-making process.)
An automated workflow
I have not yet automated the workflow because
- I am still adjusting some of the code every 2-3 days or so;
- I want to look at the output before I let it boost any toots (even unlisted, as is the default) because I’m still editing the code; and
- I haven’t got around to it yet.
When I do automate it, I will probably wrap the calls to the python in a shell script which I can then get systemd to call. I have done this in the past for other processes I wanted run on a regular basis, but it’s been several months since I did that so it’ll take some work to remind myself how to do this.
I also will want to have the script generate some more useful and concise logs (what it looked at) for debugging and review.
Questions
If you have questions please ask. I’m happy to try to explain some of the design choices, will welcome suggestions on how to improve the code of what could be improved.
There may be cleaner ways of running this code locally but the xkcd cartoon about python environments speaks to my experience.