Gradio-bot NPM

Gradio Bot

Turn any Hugging Face Space or Gradio application into a discord.js bot.

sd-gif

Installation

pnpm i -g gradio-bot

For API usage, you can install it as a dependency in your project without the -g flag.

CLI Usage

For the CLI, it requires 2 environment variables to be set:

BOT_ID: The application ID of your bot.
BOT_TOKEN: The token of your bot.

You can also set them in a .env file.

To get the bot ID and token, you need to create a bot application in the Discord Developer Portal.

Then, simply run the following command:

gradio-bot 'user/repo'

The bot will automatically register the commands and start running.

You can also pre-configure the spaces by setting the SPACES environment variable like 'user/repo1,user/repo2'.

Example

gradio-bot 'stabilityai/stable-diffusion-3-medium'

The fields on Gradio will be automatically converted to Discord command options.

options

sd3

File uploads are also supported! 🎉

file

Dynamic Management

You can also dynamically manage the spaces by using the management commands:

management list: List all the spaces that the bot is currently serving.
management add: Add a new space to the bot.
management remove: Remove a space from the bot.

Dynamic management can be disabled by setting the DISABLE_MANAGEMENT environment variable to non-empty.

Options

Use --help to see all the available options:

gradio-bot --help

Some of the options include:

--hf-token (HF_TOKEN): The Hugging Face API token to use.

API Usage

As a standalone bot

You can start a bot with the GradioBot directly.

import { Client } from "discord.js";
import { GradioBot } from "gradio-bot";

const client = new Client({ intents: [] });
const gb = await GradioBot.from(space, client);
await gb.register();
await gb.start();

You can explicitly pass the token and application ID to .register and .start, or it will try to get them from the environment variables.

As a command builder and handler

The GradioBot class is inherited from SlashCommandBuilder in discord.js, so you can use it to add new powers to your existing bot too!

To register the new commands, you can use the toJSON method:

import { GradioBot } from "gradio-bot";

const gb = await GradioBot.from(space);

// Just like what you do before, but add gb.toJSON() to the array
const commands = [...others, gb.toJSON()];
const rest = new REST().setToken(token);
await rest.put(Routes.applicationCommands(id), { body: commands });

To handle the interaction, you can use the handle method:

client.on("interactionCreate", async (interaction) => {
    if (!interaction.isChatInputCommand()) return;

    const handled = await gb.handle(interaction);
    if (handled) return;

    // The command name is not matched, do something else
    // ...
});

If you want to have more control over the interaction, you can use the parse method and respond manually:

client.on("interactionCreate", async (interaction) => {
    if (!interaction.isChatInputCommand()) return;

    if (interaction.commandName === gb.name) {
        // Parse the interaction options
        const { route, data } = gb.parse(interaction);

        // Run the prediction by yourself
        const result = await gradio.predict(route, data);

        // Create attachments for sending files (optional)
        const files = await makeAttachments(result.data);

        // Respond to the interaction manually
        await interaction.reply({ content: "Got some cool stuff!", files });
    }
});