Once your server is set up, your bot dashboard will be live at your Heroku app address, e.g. http://my-voter-bot.herokuapp.com
From the dashboard you control nearly everything. The notable exceptions are
- Heroku app variables (AKA environment variables), where you set very private data, such as your Steem posting key, username, email address, etc.
- Automatic running of the bot. To run an iteration of your bot every
Xminutes, you need to use a scheduler. This is discussed in more detail in the installation guide.
Dashboard with Start Session prompt
Through the dashboard you can access the various functions of the bot via a web interface.
In order to authenticate yourself, you need to supply your BOT_API_KEY into the clearly visible Start Session field. You set this API key when setting up the bot on Heroku or as an environment variable if a local install. It should not be confused with your Steem posting key, or SendGrid (email sender) API key.
Dashboard with session activated
If a session is invalid, either due to invalid or missing session key, or server idling or updating, you will see an error screen clearly directing you back to the dashboard.
API error page
- Run Bot
- Bot Stats
- Edit Algorithm
- Edit Config
- Test Algorithm
- Last Log
This will trigger the bot to perform what we call an iteration or run.
This means that the bot will get the latest posts from the Steem blockchain, score them and vote for any which pass the threshold.
You will see a simple full page message indicating whether the run was successful or not. Success does not necessarily mean votes were cast, but it does mean that the process was completed without any errors.
After a few moments, giving time for the votes to be cast at an interval of 3 seconds each, you can see the results in the particular results in the Last Log section and the Stats section more generally.
For details of how this process works, please see the discussion doc.
This is an invaluable tool to see whether or not your algorithm is working as you intend it. You can then make corrections to it and refine your process, based on real data.
Please note that stats are only kept for a limited number of days due to the storage limitation of the Heroku free accounts for which this set up is intended. If you have a paid plan or are using this bot locally, you can set the configuration variable DAYS_KEEP_LOGS to a larger number of days. It is set to 5 by default.
There are currently three collections of stats you can view:
- General overview
- Bot run overview
- Daily likes overview
Note that in all stats charts, if you hover your mouse over elements of the chart, a popover will display with more information about that element.
General overview page
Two charts are shown on the general overview page, which is the landing page for stats: the number of posts processed per bot run, and the number of posts liked per bot run.
Days divisions are shown by block background colour.
On the left side there is a list of links for all recorded bot runs, headed by the daily summary of likes for that day.
It is important to understand how posts are scored in relation to each other, in sequence. This is because the score threshold is adjusted for each post, including the last NUM_POSTS_FOR_AVG_WINDOW number of posts.
Bot run overview, first graph: overall post scores and threshold
The first graph shows the score of each post as a blue bar. It also shows the MIN_SCORE_THRESHOLD in gray and the current score threshold when that post was scored.
As is explained in the algorithm doc, any post score equal to or above MIN_SCORE_THRESHOLD is included in the score threshold window, which uses an adjusted averaging formula. Thus if there are a lot of posts scored low at around MIN_SCORE_THRESHOLD, the score threshold will drop, lowering the "standard" of post quality so that a moderately highly scored post is more likey to be voted on. Conversely, if the standard is very high, it is less likely a post will be voted on.
This is moderately complex, and so it's very useful to see how it actually works in graph form.
Bot run overview, second graph: metrics scoring detail
If you think too many posts are being picked, adjust you algorithm, and you can also change the third contribution to the score threshold, the SCORE_THRESHOLD_INC_PC, to increase the threshold, or in other words, demand a higher standard. By default it's set to a sensible value of 0.1 (i.e. 10%).
While the overall score is what counts, it is made up a sum of individual scores based on metrics. See the algorithm doc for more details, but each metric is multiplied by a weight which is set by you. We call the set of these weights (and the white / black-lists) the algorithm of the bot, and is set in the Edit Algo section, accessed from the dashboard.
You can see the breakdown of each individual metric score. Note that each individual score already has the algorithm applied, i.e. is metric * weight.
These are colored and displayed for each post. Positive scores stick above the horizontal x-axis, negative stick below. You can mouse over either the score bars or even the metrics key legend on the right side, to see specific information.
Bot run overview, second graph: metrics scoring detail, hover over a particular item
This is really useful for seeing whether your algorithm is contributing to the overall post scores as you intend it too. Perhaps you will see that one metric has too large or too small an effect, and so you can then adjust the weight in the Edit Algorithm seciton.
Daily likes overview, first graph: overall post scores and threshold
Once you have a handle on the bot runs, the daily likes overview will become the more important charts. It is here that you can see that the posts you are catching are the ones you want, at a glance.
You can also use it as a kind of daily round up of the posts you missed, as if you are a human you must do other things than just sit on Steemit, viewing posts!
Daily likes overview, second graph: metrics scoring detail
The charts used are the same as the ones for Bot Run, they are just applied to the liked posts, so you'll see no negative scores in the overall score, and probably very little in the metric breakdown.
Daily likes overview, second graph: metrics scoring detail, hover over a particular metric
In order for the bot to function at all, you must set your algorithm for it. To be clear, the bot server contains a lot of code already, but you need to tell it how you want to score posts. We call this the algorithm.
For a more detailed explanation, see the algorithm doc.
To summarise, there are two parts to the algorithm:
- A collection of weights
- Some white / blacklists
When the bot runs (performs an iteration on the newest posts), it scores them. The if the resulting score meets the threshold requirement, the post is voted on. The threshold is automatically adjusted for each post, more details above in the stats section, and also of course in the algorithm doc.
This score is calculated by adding up each metric you have chosen to use. Before adding them together, the metrics are scaled (and optionally confined to a range of values) using what we term weights.
You can think of a weight as the relative importance of that particular metric, with regards to its own range of values.
Some metrics are numeric and can have any number value which is sensible, and some metrics are boolean, and are 0 if false or 1 if true.
By themselves these lists do nothing but they are used for certain metrics. There are four white / blacklists:
- Author: used for when looking the poster of the article and also the voters on an article, such as
author_is_blacklisted.- Note that it is also possible to use your followed users (e.g.
author_is_followed), you don't have to add them to this list. Muted users however or inaccessible.
- Note that it is also possible to use your followed users (e.g.
- Content category and tag: used when looking at post tags, including the first tag which is also referred to as the category, such as
post_num_tags_whitelisted - Content word: used in NLP (natural language processing) metric involving keywords, such as
post_num_keywords_whitelisted - Domain: used for website links, such as
post_any_link_domains_blacklisted
Edit Algorithm, top of page
- Clicking a metric name in the reference list at the bottom of the page will add that metric to the top metric update form, for ease of use
- Clicking an existing metric name in your algorithm will add the values already set to the top metric update form, so you can update them easily
- You can delete a metric from your algorithm with the delete button on the right side
- You can export or import the entire algorithm as JSON. This is useful for sharing algorithms, or backing up.
Editing the configuration is the second way you can affect the running of your bot. These are settings, which means they are values which do not change often.
There are two categories
- Standard: most people will want to edit these
- Advanced: edit with caution, setting these incorrectly can really break the bot
Edit Configuration, top of page
Note, you can only edit one config variable at a time, and after each update you must press the corresponding update button.
You can also export or import the entire set of config variables for sharing or back up.
You can run a test of your algorithm which will score posts and generate logs and stats, but which will not actually cast votes.
View the log of your last bot run. This starts off very human readable and gets increasingly technical.
The technical part is designed with debugging and error reporting in mind, as this software is still in early release.