IYP Bot 2.0

The Idea

IYP Bot started as a human behavior mimicking bot, and ended up with an unintended idea. The idea of a general bot that could be programed with a few command over the chat. But for this idea to be implemented I needed to refactor all the existing chat bots and make a general purpose bot.

A general chat bot first recognizes a string pattern as a command, and generates a response, and/or does a process depending the on the command. For example a chat history logger, recognizes every string as a command and does the process of storing the strings, or maybe some data mining process over that.

So we need a way to define a pattern to be recognized and a way to associate a response and/or process with the defined pattern, so on the event of recognizing the pattern the bot does the process and/or responds with proper response.

This process is done by categorizing messages, and adding responses to these categories, so in the event of a string fitting in a category (recognizing the pattern) bot responds with a proper random (explained more on Message Categorization and Response Generation->Response Generation) response from that category (responding and/or doing the process). The specifics of defining these categories and responses will be discussed later on section Message Categorization and Response Generation.

For the rest of the document I use the term message for patterns defining a category, and response for a response/process associated with each category.

Permission System

Interaction Permissions

Letting every one program a bot is not a good idea, since a lot of mal-intended people exist on the chat, that may harm your system using the program, or abuse the bot to do harmful acts on the server. This brings the need for a permission system.

There are four permission levels (the higher the number of the permission the lower its rank):
1- Admin
2- Whitelisted
3- None
4- Blacklisted

All of the permission levels applies to roles, member, and channels, the only exception is that channels can't have the admin permission.

For any interaction with the bot you will need a permission. Your permission is evaluated as is explained below:

1- If the bot doesn't know any admins, the first person that sends something that the bot can receive will be assigned the first admin, so you're better off first setting the bot up and then adding it to servers.

2- Admins can assign members, roles, and channels permissions as explained above using command:

.Permission [Channel/Member/Role] [White/Black/Admin] [Tag]

3- Admins override permission of their roles and the channels they are interacting with the bot in.

4- If a member has a permission other than None assigned to him/her the permission of his roles will not influence his/her permission.

5- If a member is assigned None permission, highest ranked permission of the roles of the member, is used as the member's permission.

6- If member's permission (evaluated from rules 4 and 5) is not Admin the final permission to interact with the bot will be evaluated from the minimum of the member permission and channel permission.

7- If the final evaluated permission from rule 6 is Blacklisted the bot will ignore all of the messages from the member. If the permission is None, member can use commands that are already added to the bot by members. If the permission is Whitelisted the member can use the bot's built in commands to program the bot.

Notice: Interaction through bot's DM is possible, this means that permissions assigned to roles and channels will not apply to DM interactions.

Test/Final Feature

Every new message or response that a member submits to the bot is considered a test feature, meaning it can only be used on channels that are designated test channels, or they should be set as final feature by an Admin permissioned member.

Admins can add channels to designated test channel or remove them from designated test channels using the commands:

.AddChannelToTest
.RemoveChannelFromTest

These commands add/remove the channel they are sent in to/from designated test channel list.

Admins can set messages and responses to test/final features using the commands:

.SetMessageAsTest [Category][Message ID]
.SetMessageAsFinal[Category][Message ID]
.SetResponseAsTest [Category][Response ID]
.SetResponseAsFinal[Category][Response ID]

I will explain more on how to acquire Message ID and Response ID on section Bot Elements->Category.

Bot Elements

Programs

A program is a java source code with exactly one public class, the public static functions of the class will be accessible on messages and responses. You can add/remove/list programs using following commands:

.NewProgram [Public Class Name][Program]
.RemoveProgram [Public Class Name]
.ListPrograms

The methods you will be calling will have 2 arguments first one of type String[], and the second one of type Message from package:

de.btobastian.javacord.entities.message.Message;

So you should import this packet on your programs which will allow Discord API integration. The javacord message object passes as second argument will be the message object generated by javacord on even of the receiving the message that triggered the bot.

The return value of a method called on messages should be of type Boolean, and of type String on responses.

Resources

Each resource is a set of strings represented by a name, each string is called an element of the resource. You can manipulate resources using following commands:

.NewRes [Resource Name]
.AddToRes [Resource Name][Element1][Element2][Element3]...[Elementn]
.RemoveRes [Resource Name]
.RemoveFromRes [Resource Name][Element]
.ListRess
.ListResElements [Resource Name]

There is a default resource named * and contains every string by default.

Category

A category contains a set of messages (patterns) and a set of responses represented by a name. You can manipulate categories by following commands:

.NewCat [Category Name]
.AddMessage [Category Name][Message]
.AddResponse [Category Name][Response]
.EditMessage[Category Name][Message ID][Message]
.EditResponse[Category Name][Response ID][Response]
.RemoveCat [Category Name]
.RemoveMessage [Category Name][Message]
.RemoveResponse [Category Name][Response]
.ListCats
.ListMessages [Category Name]
.ListResponces [Category Name]

Following commands list the messages/responses with their ID:

.ListMessages [Category Name]
.ListResponces [Category Name]

Message Categorization and Response Generation

A string fits in a category if it matches any of the messages in a category. Messages and responses have the same structure.

Message/Response Structure

Each message/response is an ordered list of message parts, a message part can be one of the following:

Raw Message Part:

A raw message part is a raw string.

Mention Tag Message Part :

A mention tag message part can be the mention tag of the bot, or the mention tag of the sender of the string, each represented by @bot (bot's mention tag) and @sender (sender's mention tag).

Sytnax:

@sender
@bot

Resource Message Part:

A resource message part is an instance of a resource, with properties of ID, repetition counts, case sensitivity and the name of the corresponding resource the message part is an instance of.

Syntax:

<Resource Name>{ID}{Count}{Case Sensitivity}

ID, Count, and Case Sensitivity are optional, you can leave them empty or not even use them, any of the following are correct resources message parts:

<Resource Name>
<Resource Name>{ID/Empty}
<Resource Name>{ID/Empty}{Count/Empty}
<Resource Name>{ID/Empty}{Count/Empty}{Case Sensitivity/Empty}

ID allows the resource to be referenced and its value to be used in response generation or as input for programs and its value can be any integer, the default value is -1, any resource with an ID of -1 will be treated as if no ID is assigned to it.

Count defines the repetition count and can be any non-negative integer, * or +. * represents any repetition count including 0, + represents any positive repetition count. The default value is 1.

Case sensitivity defines the case sensitivity of the message part, it can be true (case sensitive) or false (case insensitive).

Program Message Part:

A program message part is a function call of a java static function that returns either a Boolean (on messages) or a String (on responses).

Syntax:

~ClassName.FunctionName(<ResourceName1>{ID/Empty}, <ResourceName2>{ID/Empty}...,<ResourceNamen>{ID/Empty})~

Any correct resource message part form is acceptable for function arguments.

Notice: The * resource can not be used in the argument list w/o being a reference.

A typical form of a message/response:

<greetings> @sender this is my first response, i <empty/dont>{0} want ~Program.function(<empty/dont>{0})~ program to run.

Matching a Message

A message matches a string \(S = A_{1}A_{2}A_{3}...A_{n}\) where each \(A_i\) is a sub-string of \(S\) that can have the length \(0\), if and only if for every \(i\) the \(i\)-th message part accepts \(A_i\). Each message part accepts a string as follows:

Raw Message Message Part:

A raw message part accepts a string that is equal to its raw string, the case sensitivity, is defined by the case sensitivity of the message.

Mention Tag Message Part:

A mention tag message part accepts the sender's mention tag in the case of @sender and bot's mention tag in the case of @bot.

Resource Message Part:

A resource message part accepts a string if it's a repetition of the elements of the corresponding resource by the repetition count of the message part, the case sensitivity is defined by the message part's case sensitivity.

Program Message Part:

A program message part accepts a string if the return value of its function call, is true. The arguments of the function call are resources, if these resources have IDs that are not equal to -1, they are references to resources that are used in the message that match the ID and resource name.

To generate the first argument of the function which is an array of strings, if the resource is a reference the accepted sub-string by that resource is associated with the resource, and if the resource is not a reference a random string accepted by the resource is associated with the resource.

Each element of the first argument array will be the string associated with each argument resource in order of their appearance, except the last element of the array which will be the sub-string associated with the program.

The argument resources that have an integer value for Count that is greater than 1 will be considered several resources with the same ID and name, and will have separate string in the first argument.

Notice: There are two kind of messages, interrupting and non-interrupting, if the string is matched with an interrupting message, if will not be matched by any other messages, but if it's matched by a non-interrupting message, it has a chance to be matched by other messages. For each matched message a proper response will be generated. You can use following command to change a message to interrupting and non-interrupting, by default all messages are interrupting.

.SetMessageInterrupting [Category Name][Message ID][True/False]

Response Generation

A response has the same structure of a message, the only difference is that on response generation each message part is substituted by a string as follows:

Raw Message Message Part:

A raw message part is substituted for the raw string.

Mention Tag Message Part:

A mention tag message part is substituted for the mention tag of the bot or sender, depending on the it's value being either @bot, or @sender.

Resource Message Part:

A resource message with and ID that is not -1 will be reference to the resource message part on the message with same name and id, if no such resource is found it will be treated as if it's not a reference.

If the resource message part is a reference it will be substituted for the string the referenced resource message part accepted. This can be used to use sub-strings from the message in the generated response.

If the resource message part is not a reference it's substituted for a random string that the resource message part accepts.

Program Message Part:

The program message part is substituted with it's return value. The resource message part arguments, if reference resource message parts, will be associated with the sub-string referenced resource message part has accepted other wise the resource will be associated with a random string that the resource message part accepts.

The first argument is an array of strings and each element of the array will be equal to the string associated with each resource message part, in the order of appearance.

Notice: On the even of any program returning null, the response generation will be terminated, this can be useful for logging program that don't intend to generate responses.

Notice: Some of the messages and responses can generate warnings, to receive or stop receiving warnings use follow commands:

.NotifyMeWarnings
.Don'tNotifyMeWarnings

Notice: On response generation a response is chose that the referenced resource message parts of it, bets fits the available resource message part on the message. If several of the same level of compatibility is found, a random one is chosen.

Save/Load/Merge/Reset Database

Every thing added to the bot, is considered part of it's current database, you can manipulated the database by following commands:

.SaveDatabase [File Name]
.LoadDatabase [File Name]
.MergerDatabase [File Name]
.Reset

Thanks for reading the fairly technical doc, if interested in actually using the bot join my test channel on discord: https://discord.gg/nuzz6z6
Also source code available on: https://github.com/IYP-Programer-Yeah/IYP_Bot-2.0

Also I tried to get this out as soon as possible so there are probably a lot of typos, i'll appreciate any suggestions on better phrasing, error fixings and syntax simplification.