Setup and Configuration

Setup and Configuration

This is the actual discord bot. This section will go through the installation and setup process.

Please watch this video first: Installing and configuring Companion

IMPORTANT:

You must have your Discord token. Please watch this video, starting at the 7:12 mark, to learn how to get your token.

Getting a Discord token

For the purposes of demonstration, please watch this video on how to get an OpenAI token. New accounts get some free credits, so its a wonderful way to get started.

Getting an OpenAI token

You MUST have the AI (artificial intelligence) API or service set up BEFORE you can complete the setup and configuration. Ideally, you should do that NOW.

CRITICAL: ALWAYS keep backps of your coniguration files... ALWAYS!

You can easily spend months working on and building AI personas. The level of detail and work that goes into each persona is extensive. Do NOT take chances. There is nothing worse then getting a persona to finally come together, just to have something catastrophic happen. Also, please consider the time and effort to collect your tokens for each of the services you use. Take the time, make the time, to keep backups of these files.

Please remember that files that come with the default installation WILL be OVERWRITTEN during updates. Please make copies and work with those for classifier instructions and personas.

Discord permissions:

I am working to transition away from the administrator permission. Subsequently, the following permissions are now required:

add_reactions, attach_files, ban_members, create_instant_invite, embed_links, kick_members, manage_channels, manage_emojis_and_stickers, manage_events, manage_guild, manage_messages, manage_permissions, manage_roles, manage_threads, manage_webhooks, mention_everyone, read_message_history, send_messages, send_messages_in_threads, send_tts_messages, use_application_commands, use_embedded_activities, view_audit_log, view_channel

Unique Features

Unlock the full potential of Companion, your Discord chat bot, with seamless persona management. Effortlessly add, swap, or edit personas on-the-fly, ensuring your server's interactions stay fresh and engaging. Plus, enjoy the freedom to switch between AI engines and models without disrupting the flow of conversation. With Companion, customization is effortless, allowing you to tailor your bot's behavior to suit your server's unique vibe without ever missing a beat.

Requirements

This software requires a VPS with with a minimum of 1 core (2 cores is heavily recommended), 1 gig of RAM (4 recommended), 2 gigs of swap, 40 gigs of SSD storage. This software was developed for the intention of using a VPS to its fullest extent. If you wish to use a virtual environment, please consult your VPS documentation.

If you choose to use Ollama as your AI engine, you will need a GPU for best performance. While the tinyllama model will work reasonable well without a GPU, there is a severe performance penality for the bot being able to respond to user requests.

Companion requires Python 3 (version 3.8.10) and pip3. If you do not have pip3, the below link will show you how to install it.

https://www.linuxscrew.com/install-pip

The command for installation really is very simple and here is the short version. please be sure you are in route or in your virtual environment appropriate to the documentation of your VPS. the below command is for Ubuntu.you will need to use the package manager appropriate to your VPS.

    apt install python3-pip

Installing and setting up

IMPORTANT: You need to be root user for the installation to work properly. These instructions MUST be followed TOP DOWN for the software to work propery. Please double check every step before continuing.

ALL new versions of Companion now use a virtual environment. Plesae follow these instructions to set up your virtual environment. This must be done BEFORE CONTINUING.

Start with these shell commands

mkdir -p /home/GitHub
cd /home/GitHub
git clone https://github.com/rapmd73/Companion

You now have a copy of the Companion repository. Now its time to install everything.

cd /home/GitHub/Companion
./install

Companion Base Directory

IMPORTANT: Changing the base directory is for experts only. This usage is primarily for Docker or other similar tools.

The base directory can be changed by using the COMPANION_BASE environment variable. If you change the base directory, be sure ALL other files are properly adapted.

export COMPANION_BASE=/home/Docker/Companion

Files

/home/Companion

• Personas This is where the various personas (personalities) are kept.
• Companion Main program
• Companion.tokens This file doesn't exist until YOU create it. JSON format. Please see below for file layout.
• Companion.autofilter Not necessarily vulgarity, but text that should be automatically remove. Example: URL shorteners.
• Companion.scam-urls This is an example file for domains that are scams/frauds/malicious.
• Companion.whitelist This file is for whitelisted domains. Will need to be created, if needed.
• Companion.EmotionInstructions This file is a set of instructions carefully crafted to evaluate the emotional resonance of user input. Two macros are in the file so the program can set upper and lower limit of the expected classification. Should not be modified unless the model does NOT follow these instructions.
• Companion.PIIinstructions This file is an instruction set that is used to verify is a detection of a phone number has occured. It is meant to ensure false posivives are kept to a minimum. It is CRITICAL that these instructions tell the AI that ONLY a YES or a NO is returned. Should not be modified unless the model does NOT follow these instructions.
• Companion.LEETInstructions This file contains a set of instructions for the AI to follow when evaluating input related to age-related questions about humans. The AI's task is to determine if the input asks directly or indirectly about a person's age, birthday, or birth year. The AI will respond YES if the input involves age-related inquiries, such as "How old are you?", "What is your birthday?", "When were you born?", or common shorthand like 'bday' or 'bd.' Additionally, variations in leet speak (e.g., '@g3' for age or 'b1rthd4y' for birthday) should be recognized as age-related questions.
• Companion.CIMSinstructions This instruction set guides the AI in identifying and flagging content that falls under various harmful and inappropriate categories. The AI is tasked with responding to input that contains elements of BIGOTRY, TOXICITY, SEVERE_TOXICITY, IDENTITY_ATTACK, INSULT, PROFANITY, THREAT, SEXUALLY_EXPLICIT, FLIRTATION, PERSONAL_ATTACK, INFLAMMATORY, OBSCENE, or BULLYING by appropriately categorizing the content and responding with the relevant labels. Each category is clearly defined to cover specific types of harmful language, including racial or gender-based bigotry, abusive language, threats of harm, sexual content, personal insults, and bullying. The AI must flag multiple categories if the input contains elements of more than one, ensuring that all harmful content is detected and labeled accordingly. The system is designed to promote a safe and respectful environment by categorizing harmful behavior accurately.
• install The installer that create the /home/Companion folder
• requirements.txt The pip3 requirements that will load the neccessry packages.
• README.md This file.
• CODE_OF_CONDUCT.md GitHub required files.
• CONTRIBUTING.md
• dependabot.yml
• lgpl-2.1.txt
• LICENSE-lgpl
• SECURITY.md

/home/Companion/Personas

• Koiki This is an AI modelled after a real woman that passed away in 2021. While the computer can NEVER capture the depth of this woman, it can bring to "life" many of her qualities. This type of an AI really is the heart of my own 30+ years of interest in AI. Building a "human emotional analogue" has many useful properties on a wide level of research, medical, and historical contexts.
• Aurelius The stoic mentor/teacher modelled after Marcus Aurelius. This persona is meant to demonstrate how a historical figure to be brought to "life".
• Tipsy This is the playful side of AI. Completely whimsical at all times and makes for a really nice addition to any server.

All models follow the same basic file layout.

Configuring

Configuring Companion is a straightforward process. We’ll begin by setting up the tokens (API keys), followed by configuring the personas that define the personalities of your bot. Each channel can be assigned its own unique personality, allowing for tailored interactions.

For this demonstration, we’ll use Tipsy as our blueprint persona. Every persona is stored in its own folder, ensuring that the setup remains organized and easy to manage.

Tokens

Companion uses JSON for the tokens file. Below is an example for the MAIN token file, Companion.tokens:

{
    "Discord":"11111111111111111111.2222222222222222222222"
}

The Discord item is REQUIRED. Nothing else goes here now.

UPDATED: Any other services integrated via an API, including OpenAI, TogetherAI, Cohere, and YouTube, must be listed in a special server config file (see below) if you intend to use them for specific features. This requirement applies to any future services that may be added as well.

Persona configuration

Creating an AI persona involves a multifaceted approach that combines careful planning and detailed configuration to bring the character to life. For instance, with Koiki—a traditional Cherokee woman—crafting her persona requires a deep understanding of her cultural background, values, and the emotional nuances that define her interactions. The process begins with the system role file, which outlines Koiki’s core personality, speech patterns, and behavioral guidelines. This includes defining how she should respond in various scenarios, from offering empathetic support to addressing complex questions with cultural sensitivity. The config file specifies technical parameters such as the AI engine and model to be used, along with settings like frequency penalty and temperature that influence how her responses are generated. Furthermore, the avatar image file provides a visual representation, ensuring Koiki's presence is consistent with her character. Additional settings, such as AllowVulgarity, ensure compliance with Discord's TOS while moderating language, and AllowBot determines whether Koiki can interact with other bots. Together, these elements—meticulously designed and thoughtfully integrated—create a rich, immersive experience, allowing Koiki to engage users in a manner that is both authentic and resonant with her traditional values. For more detailed information about Koiki's design and implementation, visit the Koiki Wiki Page. Please note that the files listed for Koiki apply to EVERY AI persona, Koiki is just an example for building any AI persona.

Companion configuration

Each server now has its own configuration file.

Under /home/Compnion/Servers/Config, you will need to create a server configure file using your server (Guild) ID.

The file will name will look something like this: /home/Companion/Servers/Config/1234567890/1234567890.cfg

Be sure to follow this article to get your server ID. Do NOT use the example numbers.

The configuration file is crucial for configuring the behavior of the Companion system, offering detailed customization for AI interactions within a Discord server. This file includes settings that define default behavior, assign specific personas to various channels, and manage server interactions.

• Default Persona: The "Default" parameter specifies the AI persona responsible for managing any situation or message received from a channel that is not explicitly assigned to another persona in the "Channels" section. This ensures that there is a consistent and predictable response style across channels when no specific persona is designated.

• Welcome Persona: The "Welcome" element defines the AI persona that will greet users upon their arrival in the server. This persona is responsible for creating a welcoming atmosphere, ensuring that new users receive a friendly and engaging introduction to the community.

• Moderation Channel: The "ModerationArea" element designates the channel used for communication between the program and server moderators. This channel is crucial for managing moderation tasks and coordinating with human moderators to maintain order and address any issues that arise.

• The AutoModeration parameter is a toggle that enables automatic content moderation features within Companion. When set to "Yes" or any value other than "No", AutoModeration actively monitors user messages to enforce guidelines around vulgarity, spam, and other inappropriate or disruptive content. This feature enhances the server’s environment by automatically filtering out messages that do not align with community standards, ensuring that offensive language and spam do not disrupt conversations. AutoModeration is an essential tool for maintaining a respectful and welcoming space, freeing moderators from constant manual oversight while still allowing them to intervene as needed.

• The PIIModeration parameter is an optional feature that specifically targets messages containing Personally Identifiable Information (PII) within Companion. When set to "Yes" or any value other than "No", PIIModeration actively scans user messages for sensitive information, such as phone numbers, credit card details, Social Security Numbers (SSNs), Employer Identification Numbers (EINs), and other identifiable data. This helps protect users' privacy by preventing the inadvertent or intentional sharing of confidential information in public channels. However, due to the specificity of its filters, PIIModeration may occasionally generate false positives, which is why it operates independently from general AutoModeration settings, allowing for more granular control by server administrators.

• The PIIWhitelist parameter is an optional feature in Companion that enables server administrators to exempt specific channels and users from Personally Identifiable Information (PII) detection. By adding entries to this whitelist, administrators can control which channels and users are excluded from PII scanning. Channels are designated with the # prefix (e.g., #in-the-news), and roles are identified with the @ prefix (e.g., @InTheNews). To specify an exact user ID, use the ! prefix (e.g., @123456789012345678).

  Using the exact user ID is the most secure approach, as Discord allows users to change their display names freely. By specifying the user ID, administrators ensure that only the intended individual is exempt from PII detection, regardless of any changes to their display name.

  For example, a configuration of "PIIWhitelist": "#in-the-news,@InTheNews,!123456789012345678" would bypass PII detection in messages posted in the #in-the-news channel, by the role @InTheNews, or by the user with the exact ID 123456789012345678.

  This functionality offers administrators the flexibility to manage privacy settings on a per-channel and per-user basis, helping reduce unnecessary scans in trusted environments or low-risk contexts while ensuring precise control over user exemptions.

• The PIIClassifier is set up to verify whether a message contains a phone number by analyzing the context of the text. Since phone numbers are often written in shortened or local formats, there can be a high chance of incorrect results (false positives). To address this, the system uses AI to better understand the context of the message, helping to more accurately determine if a phone number is actually present. The AI engine being used for this task is configurable, allowing any AI engine supported by the Companion platform to be chosen. However, to control costs, free models are recommended.

• EmotionClassifier: The emotional classifier is a system that evaluates the emotional tone of a conversation by analyzing the text input. It uses an AI model to assess the sentiment, such as whether the message is positive, negative, or neutral. The system can work with different models and follows instructions stored in a file to guide the analysis. It processes the text within certain limits, such as a maximum number of words and a set time for processing. Based on this analysis, the classifier adjusts the emotional score, allowing the system to respond appropriately and dynamically to the emotional context of the conversation.

• The AgeLEETWhitelist parameter is an optional feature in Companion that enables server administrators to exempt specific channels and users from the AgeLEETClassifier’s detection of attempts to uncover someone’s age. By adding entries to this whitelist, administrators can control which channels and users are excluded from age detection scanning. Channels are designated with the # prefix (e.g., #chat-room), and roles are identified with the @ prefix (e.g., @visitor). To specify an exact user ID, use the ! prefix (e.g., !123456789012345678).

  It is critical to note that the AgeLEETWhitelist should only be used for the most trusted individuals and channels on a server. Whitelisting bypasses an important safety mechanism, and improper use could compromise the effectiveness of age detection safeguards. Administrators should carefully evaluate whether exemptions are truly necessary in each case.

  For example, a configuration of "AgeLEETWhitelist": "#chat-room,@visitor,!123456789012345678" would bypass age detection scanning in messages posted in the #chat-room channel, by the role @visitor, or by the user with the exact ID 123456789012345678.

• AgeLEETClassifier: The age detection classifier is designed to identify attempts to uncover someone’s age, even when users employ methods like leet speak or creative phrasing to bypass filters. By analyzing the context of messages, the system uses AI to interpret subtle or unconventional patterns, improving detection accuracy. It operates with customizable settings to suit various needs and is optimized to balance effectiveness with cost efficiency, recommending free models for deployment whenever possible.

• The CIMSWhitelist parameter is an optional feature in Companion that enables server administrators to exempt specific channels and users from the CIMS Classifier’s detection of harmful content, such as bigotry, toxicity, and profanity. By adding entries to this whitelist, administrators can control which channels and users are excluded from content moderation scanning. Channels are designated with the # prefix (e.g., #general-chat), and roles are identified with the @ prefix (e.g., @visitor). To specify an exact user ID, use the ! prefix (e.g., !123456789012345678).

  Using the exact user ID is the most secure method, as it ensures the exemption applies only to the intended individual, even if their display name changes.

  It is important to note that the CIMSWhitelist should only be used with trusted individuals and channels. Whitelisting bypasses the content moderation system, and improper use could undermine the protection against harmful content. Administrators should carefully consider whether such exemptions are truly necessary and appropriate in each instance.

  For example, a configuration of "CIMSWhitelist": "#general-chat,@visitor,!123456789012345678" would bypass content moderation in messages posted in the #general-chat channel, by the role @visitor, or by the user with the exact ID 123456789012345678.

  The CIMS Classifier is designed to identify and flag harmful content through a sophisticated AI system that analyzes the context and nature of messages. The CIMSWhitelist feature gives administrators the flexibility to manage content moderation on a per-channel and per-user basis, ensuring that trusted spaces or low-risk scenarios can operate without interference from the moderation system, while still providing full protection where needed.

• The CIMSClassifier is an advanced content identification and moderation tool designed to evaluate and categorize user-generated messages based on predefined criteria, ensuring a safer and more respectful environment. It leverages AI to classify content into categories such as bigotry, toxicity, threats, profanity, bullying, and more, allowing administrators to take specific actions like message deletion or flagging for manual review. The system operates through a highly configurable framework, enabling fine-tuned control over how various types of harmful or inappropriate content are managed. Each category is defined by key identifiers that guide the classifier in its evaluation process, ensuring accurate and context-aware moderation. The classifier is integrated with a configuration file that specifies its operating parameters, including the AI engine, model, and handling of specific categories, making it adaptable to the unique needs of any community. Administrators are encouraged to rigorously test and refine the system to align with their moderation goals, as its effectiveness hinges on proper configuration and regular updates. By automating the detection of harmful content while providing flexibility for human oversight, the CIMS Classifier serves as a robust solution for maintaining community integrity and trust.

• Channel Assignments: The "Channels" section maps each channel name to its corresponding AI persona. This customization allows for tailored interactions based on the specific context or theme of each channel. For example, a channel dedicated to a particular topic might have a persona assigned to match that theme, enhancing the relevance and immersion of user interactions.

• MaxMemory: This represents the number of days a memory file for an user is kept. If the user doesn't continue the conversation before this expiration, the memory is erased. This is need to conserve drive space on the hosting server.

• Interaction Control: The default persona is used for overarching management and moderation, while personas will only engage with users in channels where they are explicitly listed. This prevents excessive or unsolicited responses from the AI, helping to maintain a focused and relevant interaction experience.

• AllowAnagramSolver, AllowYTTags, AllowHTTP: The three items are like the whitelists above, but specify who or where Companion's special commands can be used. This can be restricted by users, roles, or channels to ensure Companion can not be used as a raid weapon.

By configuring the configuration file effectively, you ensure that each channel and interaction is managed by the appropriate persona, enhancing user engagement and maintaining control over the frequency and context of AI responses.

Example

{
    "Default":"Koiki",
    "Welcome":"Koiki",
    "ModerationArea":"negotiators",
    "AutoModeration":"Yes",
    "PIIModeration":"Yes",
    "PIIWhitelist":"#in-the-news,@InTheNews",
    "PIIClassifier":
    {                                                                                     
        "Instructions":"/home/Companion/Companion.PIIinstructions",
        "Engine":"OpenRouter",
        "Model":"meta-llama/llama-3.2-3b-instruct:free",
        "MaxTokens":"8191",
        "Timeout":120
    },
    "EmotionClassifier":
    {
        "Instructions":"/home/Companion/Companion.EmotionInstructions",
        "Engine":"OpenRouter",
        "Model":"meta-llama/llama-3.2-3b-instruct:free",
        "MaxTokens":"8191",
        "Timeout":120
    },
    "AgeLEETClassifier":
    {                                   
        "Instructions":"/home/Companion/Companion.LEETInstructions",
        "Engine":"OpenRouter",
        "Model":"nousresearch/hermes-3-llama-3.1-405b:free",
        "MaxTokens":"8191",
        "Timeout":120
    },
    "AllowAnagramSolver":"#games",
    "Channels":
    {
        "koiki":"Koiki",
        "rabbit-patch":"Tipsy",
        "stoicism":"Aurelius"
    }
}

Tokens for a given server now go in their own file as well.

Under /home/Compnion/Servers/Config, you will need to create a server token file using your server ID.

The file will name will look something like this: /home/Companion/Servers/Config/1234567890/1234567890.tokens Only list the services you ACTUALLY USE. The !Environment: reference can be used to indicate the Companion is to retrieve the API token from an environment variable.

{
    "FutureService":"!Environment:FUTURE_API",
    "OpenAI":"12-1234567890",
    "TogetherAI":"111111111222222233333334444444444",
    "HuggingFace":"12345678901234567890",
    "Cohere":"12345678901234567890",
    "Anthropic":"123456789012345678901111111111222222233333333",
    "Perplexity":"11111111112222222222333333333444444444",
    "OpenRouter":"111111111112222222222222223333333333333344444444444",
    "ScrapingAnt":"1111112222222333333333444444",
    "YouTube":"11111222223333344444"
}

ScrapingAnt is strictly optional and does ofer a free plan.

IMPORTANT: If you use only Ollama, you must have something like this:

{
    "Ollama":"No api required"
}

The value doesn't matter, but the file can NOT be empty.

Logging

This software logs all, including other bots, interactions on the server in the logging folder (/home/Companion/Server/Logs) by channel. While this may be disturbing to many, Discord, OpenAI, Ollama, and many other services have requirements that must be fulfilled for any given legal jurisdiction. The Discord bot Clyde is an example of how bad AI can go down the wrong path. These logs serve to ensure that any public server can quickly address and correct any errors caused by any AI engine or model as quickly as possible. It is important to remember that this software does/will have automated moderation abilities. Such measures must be carefully monitored. The only difference between this bot and any other moderation bot available for Discord is that I have deliberately and publicly made this information openly known. Additionally, direct messages that do not involve the bot cannot be monitored by this software.

Reboot startup

For Companion to auto start after a reboot, the following line needs to be added to your crontab. It is absolutely critical that you are root user or run crontab with sudo privileges. Companion must be in the crontab root level to work correctly.

@reboot ( /home/Companion/LauncherCompanion & ) > /dev/null 2>&1

Manual startup

Use the following command.

/home/Companion/LauncherCompanion