Port mtrix DiscordClient class to mindtrace

[JeremyWurbs]

This PR ports the old DiscordClient class from mtrix. It also updates the client to utilize slash commands.

DiscordClient Usage

First, create your own Discord server and bot, and add the bot to your server. You can find a comprehensive guide on how to do this here. The process should only take 5 minutes. Place the bot's API key in your config.ini file at [MINDTRACE_API_KEYS][DISCORD], set the associated MINDTRACE_API_KEYS__DISCORD environment variable, or directly pass the token into the following command.

To run the integration tests, also place the same (or an additional bot key) at [MINDTRACE_TESTING_API_KEYS][DISCORD].

Then test the above with the associated DiscordClient bot sample:

$ uv run mindtrace/services/samples/discord/custom_bot_client.py

If the bot successfully launches, you will get the following message:

% uv run python mindtrace/services/mindtrace/services/samples/discord/custom_bot_implementation.py
No token provided via --token.
The bot will attempt to use MINDTRACE_API_KEYS__DISCORD from Mindtrace config.
Registering slash commands...
Registered 4 slash commands
Starting Discord bot...
Syncing 4 commands...
Successfully synced 4 command(s)

In any chat or DM the bot has access to, type slash / to list the bot commands:

If the bot has the requisite permissions, all of the example commands should work. Commands with extra inputs will display them as separate input boxes:

Custom handlers are also supported. Refer to the example code for a custom handler for DMs:

from mindtrace.services.discord.discord_client import DiscordEventHandler

class CustomEventHandler(DiscordEventHandler):
    """Custom event handler for demonstration."""
    
    async def handle(self, event_type: DiscordEventType, **kwargs):
        """Handle Discord events with custom logic."""
        if event_type == DiscordEventType.MESSAGE:
            message = kwargs.get('message')
            if message and "hello" in message.content.lower():
                await message.channel.send("Hello there! 👋")

DiscordService class

The above sample uses the DiscordClient class, which derives from the Mindtrace class. There is a separate DiscordService class derived from the mindtrace Service class with associated functionality. You can run the associated sample with:

$ uv run mindtrace/services/samples/discord/custom_bot_service.py

Running the Discord bot as a Service enables using the bot's slash commands through the generated connection manager's discord_execute command:

from mindtrace.services.samples.discord.custom_bot_service import CustomDiscordService

cm = CustomDiscordService.launch()  # launches both the DiscordClient and a separate FastAPI app
result = cm.discord_execute(content="/roll 20")
print(f"Result: {result.response}")  # Result: You rolled a 12 (1-20)

Note the following arguments are always provided by Discord when calling the bot through Discord. If your slash command uses them (e.g. for some guild commands), you will have to pass them in through the the above command as well: author_id, channel_id, guild_id, message_id.

Docs & Testing

Unit tests, integration tests and samples have been provided. Run the discord test suite with

ds test: tests/unit/mindtrace/services/discord \
tests/unit/mindtrace/services/samples/discord \
tests/integration/mindtrace/services/test_discord_service_integration.py \
tests/integration/mindtrace/services/test_discord_samples_integration.py

All tests should pass.

The two samples can be run with:

$ uv run mindtrace/services/samples/discord/custom_bot_client.py

$ uv run mindtrace/services/samples/discord/custom_bot_service.py

After running either sample above, you should be able to use and communicate with the bot on the associated Discord server.