# aho
General purpose Discord bot.
## Installation
### Requirements
- python3 (>=3.11.2) with pip
- virtualenv
### Clone and install in virtualenv
- `git clone git@gitlab.com:nul.one/aho.git`
- `cd aho`
- setup and enable virtualenv with correct version of python
- `pip install ./aho`
### Install from pypi
`pip install aho`
__Note that running aho bot will create a socket file in current directory.__
## Usage
- `aho --help` - show available commands
- `aho run --help` - show options for running
You can run the bot with these minimal options:
`aho run -t DISCORD_AUTHORIZATION_TOKEN --database SQLITE_DB_FILE_PATH`
### Additional run options and environment varibles
Each of these variables can be set using corresponding env variable. If both command line option and env variable are present, the command line option will be used.
- `-t, --token` or export `TOKEN` Discord bot authorization token.
- `-o, --owner` or export `OWNER` Bot owner (dev) Discord user ID.
- `--database` Path to sqlite database file. If not provided, it will use ephemeral database in ram.
- `--prefix` or export `DEFAULT_PREFIX` Default prefix in guilds. Each guild prefix can be configured in the guild itself.
- `--description` or export `BOT_DESCRIPTION` Bot description that shows up in guild commands help printout.
- `-n, --name` or export `BOT_NAME` Bot name that shows up in guild commands help printout.
- `--openai` or export `OPENAI_API_KEY` OpenAI API secret key.
- `--openai-system-message` or export `OPENAI_SYSTEM_MESSAGE` Default ChatGPT system message if you want to customize it.
- `-l, --log-file` Log file path.
## Features
These are the features as used from Discord. All of these should start with a bot prefix (default is `aho `) specific for each guild.
### Metadata
Metadata is a list of key/value pairs associated with either a guild, channel, user or member. You can create any key/value pair. Some specific keys are used by other extensions and features. Having an unrestricted key/value pair simplifies configuration of existing features or adding new features in the future.
Here is a list of commands for manipulating metadata:
- `meta (guild|CHANNEL_TAG|MEMBER_TAG) (get|set) KEY [VALUE]` This will get the value of a key for selected entity or set the new value.
The guild as an entity is just a literal word "guild" or "g" for short. There is no tag for a guild. E.g. `meta g set prefix ~`.
If you want to delete a key/value entry, use set command without the value. E.g. `meta g set openai_api_key`.
To list keys/vlues, omit key when getting. E.g. `meta #general get`.
__User meta__
This is separate command to manipulate user specific metadata as opposed to a member. Member is user entity tied to a guild. User metadata is same across all guilds for a specific user. As such, this command is restricted to a bot owner (see `--owner` option in instructions on how to run the bot).
The command is similar to how `meta` works:
- `umeta (MEMBER_TAG|DISCORD_USER_ID) (get|set) KEY [VALUE]`
### Moderation commands
These commands are used for user/channel/guild moderation and are available to users with those specific permissions.
- `ban (MEMEBER_TAG|DISCORD_USER_ID) [REASON]` ban a user.
- `unban (MEMEBER_TAG|DISCORD_USER_ID)` lift a user ban.
- `kick (MEMEBER_TAG|DISCORD_USER_ID) [REASON]` kick a user from guild.
- `perms (MEMEBER_TAG|DISCORD_USER_ID)` display member permissions in guild.
- `clear [N]` delete N lines (defaults to 1) right above in the current channel.
### OpenAI (ChatGPT) chat
There are 2 modes of chatting with ChatGPT bot: using chat command and using a chat specific channel. ChatGPT 3.5 is being used as of the time of writing this manual.
__Chat command__
Guild level metadata values should be configured:
- `openai_api_key` Put your OpenAI API key here. Alternatively, you can specify this value when running the bot with `--openai` option or exporting `OPENAI_API_KEY` environment variable. Note that by doing so the api will be enabled by default on all guilds. I recommend having a specific setting in metadata for each guild if your discord bot is publically available.
- `openai_system_message` This is optional and is used if you want to customize your ChatGPT experience.
Using a `chat` command, e.g. `chat Hello! Can you tell me the radius of Earth?` will initiate a respons from the bot in all channels.
__Chat channel__
You can configure one channel that will always initiate a response from a bot, no commands need to be used in it. To configure a channel for this, set these meta variables at the channel level:
- `openai_chat_enabled` Set it to `1` to start using this channel as dedicated for a chatbot interraction.
- `openai_system_message` Optional, same as for `chat` command. Each dedicated channel can have specific ChatGPT customization.
You still need an `openai_api_key` set at the guild level for this dedicated channel chat to work.
### Points
Members who have permission to manage other members can use the point system. Point system is used to award other members for any deeds or to promote competitive environment. It's up to you on how you will use this feature.
- `transaction (MEMBER_TAG|DISCORD_USER_ID) AMOUNT [DESCRIPTION]` Add (or remove by adding negative AMOUNT) points to a member.
Points can be visible in the member info (see info command).
### Member Info
Use this command to see following information about a member:
- number of points
- guild joining date and joining position
- guild roles
- discord account creation date
Use it as so `info ` If you don't provide a member tag or ID, it will show your own info.
### Roll
Roll dice in NdN format, first number being number of dice and second being number of sides on each die.
- `roll [NdN]` Default is 1d6 which you can use without arguments.
### Emoji
- `addemoji EMOJI NAME` Copy an existing emoji (that you can access from another server with Discord premium) and add it to the current server under a new NAME.
- `getemoji EMOJI` Get a link to the emoji image or animation.
### General purpose commands
- `help [command]` Show usage of specific command. If you don't specify a command, it will list all commands with short description.
- `avatar [MEMBER_TAG|DISCORD_USER_ID]` It will reply with a member avatar image. If you don't provide a member tag or ID, it will show your own avatar.
- `embed "Some Title" Some message.` This will create an embeded message in a current channel and delete your command message. Used to create emphasized messages.
- `info [MEMBER_TAG|DISCORD_USER_ID]` Show member info, including number of points, guild joining date and position, guild roles and discord account creation date. If you don't specify a member, your own info will be shown.
- `prefix NEW_PREFIX` Set new Discord bot prefix at a guild level.
- `version` Display the current bot version.
## Versioning and compatibility
Starting from version `1.3.0` the versions will follow [Semantic versioning v2.0.0](https://semver.org).
## License
[3-Clause BSD License](https://opensource.org/license/bsd-3-clause/) which you can see in the LICENSE file.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/nul.one/aho",
"name": "aho",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11.2",
"maintainer_email": "",
"keywords": "",
"author": "Predrag Mandic",
"author_email": "predrag@nul.one",
"download_url": "https://files.pythonhosted.org/packages/92/78/c7546732dcc1766afeaf4036803020b82aa23b3aa1cb509a65676b92992e/aho-1.3.2.tar.gz",
"platform": null,
"description": "# aho\n\nGeneral purpose Discord bot.\n\n## Installation\n\n### Requirements\n\n- python3 (>=3.11.2) with pip\n- virtualenv\n\n### Clone and install in virtualenv\n\n- `git clone git@gitlab.com:nul.one/aho.git`\n- `cd aho`\n- setup and enable virtualenv with correct version of python\n- `pip install ./aho`\n\n### Install from pypi\n\n`pip install aho`\n\n__Note that running aho bot will create a socket file in current directory.__\n\n## Usage\n\n- `aho --help` - show available commands\n- `aho run --help` - show options for running\n\nYou can run the bot with these minimal options:\n\n`aho run -t DISCORD_AUTHORIZATION_TOKEN --database SQLITE_DB_FILE_PATH`\n\n### Additional run options and environment varibles\n\nEach of these variables can be set using corresponding env variable. If both command line option and env variable are present, the command line option will be used.\n\n- `-t, --token` or export `TOKEN` Discord bot authorization token.\n- `-o, --owner` or export `OWNER` Bot owner (dev) Discord user ID.\n- `--database` Path to sqlite database file. If not provided, it will use ephemeral database in ram.\n- `--prefix` or export `DEFAULT_PREFIX` Default prefix in guilds. Each guild prefix can be configured in the guild itself.\n- `--description` or export `BOT_DESCRIPTION` Bot description that shows up in guild commands help printout.\n- `-n, --name` or export `BOT_NAME` Bot name that shows up in guild commands help printout.\n- `--openai` or export `OPENAI_API_KEY` OpenAI API secret key.\n- `--openai-system-message` or export `OPENAI_SYSTEM_MESSAGE` Default ChatGPT system message if you want to customize it.\n- `-l, --log-file` Log file path.\n\n## Features\n\nThese are the features as used from Discord. All of these should start with a bot prefix (default is `aho `) specific for each guild.\n\n### Metadata\n\nMetadata is a list of key/value pairs associated with either a guild, channel, user or member. You can create any key/value pair. Some specific keys are used by other extensions and features. Having an unrestricted key/value pair simplifies configuration of existing features or adding new features in the future. \n \nHere is a list of commands for manipulating metadata:\n\n- `meta (guild|CHANNEL_TAG|MEMBER_TAG) (get|set) KEY [VALUE]` This will get the value of a key for selected entity or set the new value.\n\nThe guild as an entity is just a literal word \"guild\" or \"g\" for short. There is no tag for a guild. E.g. `meta g set prefix ~`.\n\nIf you want to delete a key/value entry, use set command without the value. E.g. `meta g set openai_api_key`.\n\nTo list keys/vlues, omit key when getting. E.g. `meta #general get`.\n\n__User meta__\n\nThis is separate command to manipulate user specific metadata as opposed to a member. Member is user entity tied to a guild. User metadata is same across all guilds for a specific user. As such, this command is restricted to a bot owner (see `--owner` option in instructions on how to run the bot).\n\nThe command is similar to how `meta` works:\n\n- `umeta (MEMBER_TAG|DISCORD_USER_ID) (get|set) KEY [VALUE]`\n\n### Moderation commands\n\nThese commands are used for user/channel/guild moderation and are available to users with those specific permissions.\n\n- `ban (MEMEBER_TAG|DISCORD_USER_ID) [REASON]` ban a user.\n- `unban (MEMEBER_TAG|DISCORD_USER_ID)` lift a user ban.\n- `kick (MEMEBER_TAG|DISCORD_USER_ID) [REASON]` kick a user from guild.\n- `perms (MEMEBER_TAG|DISCORD_USER_ID)` display member permissions in guild.\n- `clear [N]` delete N lines (defaults to 1) right above in the current channel.\n\n### OpenAI (ChatGPT) chat\n\nThere are 2 modes of chatting with ChatGPT bot: using chat command and using a chat specific channel. ChatGPT 3.5 is being used as of the time of writing this manual.\n\n__Chat command__\n\nGuild level metadata values should be configured:\n\n- `openai_api_key` Put your OpenAI API key here. Alternatively, you can specify this value when running the bot with `--openai` option or exporting `OPENAI_API_KEY` environment variable. Note that by doing so the api will be enabled by default on all guilds. I recommend having a specific setting in metadata for each guild if your discord bot is publically available.\n- `openai_system_message` This is optional and is used if you want to customize your ChatGPT experience.\n\nUsing a `chat` command, e.g. `chat Hello! Can you tell me the radius of Earth?` will initiate a respons from the bot in all channels.\n\n__Chat channel__\n\nYou can configure one channel that will always initiate a response from a bot, no commands need to be used in it. To configure a channel for this, set these meta variables at the channel level:\n\n- `openai_chat_enabled` Set it to `1` to start using this channel as dedicated for a chatbot interraction.\n- `openai_system_message` Optional, same as for `chat` command. Each dedicated channel can have specific ChatGPT customization.\n\nYou still need an `openai_api_key` set at the guild level for this dedicated channel chat to work.\n\n### Points\n\nMembers who have permission to manage other members can use the point system. Point system is used to award other members for any deeds or to promote competitive environment. It's up to you on how you will use this feature.\n\n- `transaction (MEMBER_TAG|DISCORD_USER_ID) AMOUNT [DESCRIPTION]` Add (or remove by adding negative AMOUNT) points to a member.\n\nPoints can be visible in the member info (see info command).\n\n### Member Info\n\nUse this command to see following information about a member:\n\n- number of points\n- guild joining date and joining position\n- guild roles\n- discord account creation date\n\nUse it as so `info ` If you don't provide a member tag or ID, it will show your own info.\n\n### Roll\n\nRoll dice in NdN format, first number being number of dice and second being number of sides on each die.\n\n- `roll [NdN]` Default is 1d6 which you can use without arguments.\n\n### Emoji\n\n- `addemoji EMOJI NAME` Copy an existing emoji (that you can access from another server with Discord premium) and add it to the current server under a new NAME.\n- `getemoji EMOJI` Get a link to the emoji image or animation.\n\n### General purpose commands\n\n- `help [command]` Show usage of specific command. If you don't specify a command, it will list all commands with short description.\n- `avatar [MEMBER_TAG|DISCORD_USER_ID]` It will reply with a member avatar image. If you don't provide a member tag or ID, it will show your own avatar.\n- `embed \"Some Title\" Some message.` This will create an embeded message in a current channel and delete your command message. Used to create emphasized messages.\n- `info [MEMBER_TAG|DISCORD_USER_ID]` Show member info, including number of points, guild joining date and position, guild roles and discord account creation date. If you don't specify a member, your own info will be shown.\n- `prefix NEW_PREFIX` Set new Discord bot prefix at a guild level.\n- `version` Display the current bot version.\n\n## Versioning and compatibility\n\nStarting from version `1.3.0` the versions will follow [Semantic versioning v2.0.0](https://semver.org).\n\n## License\n\n[3-Clause BSD License](https://opensource.org/license/bsd-3-clause/) which you can see in the LICENSE file.\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "aho - a Discord bot.",
"version": "1.3.2",
"project_urls": {
"Download": "https://gitlab.com/nul.one/aho/-/archive/1.3.2/aho-1.3.2.tar.gz",
"Homepage": "https://gitlab.com/nul.one/aho"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9278c7546732dcc1766afeaf4036803020b82aa23b3aa1cb509a65676b92992e",
"md5": "1282c541f63d5d63d5feb2aa29b299fe",
"sha256": "dbafb2ebcaa89877cea90b74bd30b712c33b81e977c7ec28ddee09e25a444de7"
},
"downloads": -1,
"filename": "aho-1.3.2.tar.gz",
"has_sig": false,
"md5_digest": "1282c541f63d5d63d5feb2aa29b299fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11.2",
"size": 21383,
"upload_time": "2024-02-13T16:49:59",
"upload_time_iso_8601": "2024-02-13T16:49:59.326819Z",
"url": "https://files.pythonhosted.org/packages/92/78/c7546732dcc1766afeaf4036803020b82aa23b3aa1cb509a65676b92992e/aho-1.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-13 16:49:59",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "nul.one",
"gitlab_project": "aho",
"lcname": "aho"
}
JSON