feat: ai plugin

Author: twlite

.github/workflows/publish-dev.yaml

@@ -59,6 +59,7 @@ jobs:
             "@commandkit/devtools:packages/devtools"
             "@commandkit/cache:packages/cache"
             "@commandkit/analytics:packages/analytics"
+            "@commandkit/ai:packages/ai"
           )
 
           for entry in "${PACKAGES[@]}"; do
@@ -80,6 +81,7 @@ jobs:
             "@commandkit/devtools"
             "@commandkit/cache"
             "@commandkit/analytics"
+            "@commandkit/ai"
           )
 
           for pkg in "${PACKAGES[@]}"; do

apps/website/docs/guide/06-plugins/official-plugins/06-ai.mdx

@@ -0,0 +1,10 @@
+---
+title: AI Plugin
+description: Learn how to use the AI plugin to power your bot's commands and events.
+---
+
+## AI Plugin
+
+The AI plugin allows you to execute your bot commands using large language models. This enables you to use your bot's features entirely through natural language.
+
+Please refer to the [AI Powered Commands](../../13-ai-powered-commands/01-introduction.mdx) guide for more details.

apps/website/docs/guide/13-ai-powered-commands/01-introduction.mdx

@@ -0,0 +1,135 @@
+---
+title: AI Powered Commands
+description: Learn how to use a large language model to power your commands.
+---
+
+## Introduction
+
+CommandKit's `@commandkit/ai` plugin allows you to execute your bot commands using large language models. This enables you to use your bot's features entirely through natural language.
+
+:::warning
+This is an experimental feature and is subject to change.
+:::
+
+## Installation
+
+```bash
+npm install @commandkit/ai
+```
+
+## Usage
+
+```typescript title="commandkit.config.ts"
+import { defineConfig } from 'commandkit';
+import { ai } from '@commandkit/ai';
+
+export default defineConfig({
+  plugins: [ai()],
+});
+```
+
+## Setting up the AI model
+
+CommandKit allows you to dynamically specify the AI model to use for your bot.
+
+```typescript title="src/ai.ts"
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { configureAI } from '@commandkit/ai';
+
+const google = createGoogleGenerativeAI({
+  apiKey: process.env.GOOGLE_API_KEY,
+});
+
+const model = google.languageModel('gemini-2.0-flash');
+
+configureAI({
+  // commandkit will call this function
+  // to determine which AI model to use
+  selectAiModel: async () => {
+    return { model };
+  },
+  messageFilter: async (message) => {
+    // only respond to messages in guilds that mention the bot
+    return (
+      message.inGuild() && message.mentions.users.has(message.client.user.id)
+    );
+  },
+});
+```
+
+Now you can simply import this file in your `app.ts`,
+
+```ts title="app.ts"
+import { Client } from 'discord.js';
+// simply import the ai file
+import './ai';
+
+const client = new Client({...});
+
+export default client;
+```
+
+## Creating AI commands
+
+AI commands can be created by exporting a function called `ai` from your command file. You can also export `aiConfig` object along with the `ai` function to specify the parameters for the command.
+
+```typescript title="src/commands/balance.ts"
+import { ApplicationCommandOptionType } from 'discord.js';
+import { CommandData, ChatInputCommand } from 'commandkit';
+import { AiCommand } from '@commandkit/ai';
+import { z } from 'zod';
+
+export const command: CommandData = {
+  name: 'balance',
+  description: 'Get the current balance of the user.',
+  options: [
+    {
+      name: 'user',
+      description: 'The user to get the balance for.',
+      type: ApplicationCommandOptionType.User,
+    },
+  ],
+};
+
+export const aiConfig: AiConfig = {
+  parameters: z.object({
+    userId: z.string().describe('The ID of the user to get the balance of'),
+  }),
+};
+
+export const chatInput: ChatInputCommand = async (ctx) => {
+  const { interaction } = ctx;
+  const user = interaction.options.getUser('user');
+  const balance = await db.getBalance(user.id);
+
+  await interaction.reply({
+    content: `The balance of ${user.username} is ${balance}`,
+  });
+};
+
+// AI will call this function to get the balance of the user
+export const ai: AiCommand = async (ctx) => {
+  const { userId } = ctx.params;
+  const balance = await db.getBalance(userId);
+
+  // return object with the balance
+  return {
+    userId,
+    balance,
+  };
+};
+```
+
+Now, you can simply mention the bot in a message to get the balance of the user. Eg:
+
+```text
+@bot what is the balance of @user?
+```
+
+AI can also call multiple commands in a single message. Eg:
+
+```text
+@bot show me the basic details of the user @user and also include the balance of that user.
+```
+
+The above prompt will call the built-in `getUserInfo` tool and the `balance` command.