|
| 1 | +--- |
| 2 | +title: AI Chat Plugin |
| 3 | +description: Add AI-powered chat functionality with conversation history, streaming, and customizable models |
| 4 | +--- |
| 5 | + |
| 6 | +import { Tabs, Tab } from "fumadocs-ui/components/tabs"; |
| 7 | +import { Callout } from "fumadocs-ui/components/callout"; |
| 8 | + |
| 9 | +## Installation |
| 10 | + |
| 11 | +Follow these steps to add the AI Chat plugin to your Better Stack setup. |
| 12 | + |
| 13 | +### 1. Add Plugin to Backend API |
| 14 | + |
| 15 | +Import and register the AI Chat backend plugin in your `better-stack.ts` file: |
| 16 | + |
| 17 | +```ts title="lib/better-stack.ts" |
| 18 | +import { betterStack } from "@btst/stack" |
| 19 | +import { aiChatBackendPlugin } from "@btst/stack/plugins/ai-chat/api" |
| 20 | +import { openai } from "@ai-sdk/openai" |
| 21 | +// ... your adapter imports |
| 22 | + |
| 23 | +const { handler, dbSchema } = betterStack({ |
| 24 | + basePath: "/api/data", |
| 25 | + plugins: { |
| 26 | + aiChat: aiChatBackendPlugin({ |
| 27 | + model: openai("gpt-4o"), // Or any LanguageModel from AI SDK |
| 28 | + hooks: { |
| 29 | + onBeforeChat: async (messages, context) => { |
| 30 | + // Optional: Add authorization logic |
| 31 | + return true |
| 32 | + }, |
| 33 | + } |
| 34 | + }) |
| 35 | + }, |
| 36 | + adapter: (db) => createMemoryAdapter(db)({}) |
| 37 | +}) |
| 38 | + |
| 39 | +export { handler, dbSchema } |
| 40 | +``` |
| 41 | + |
| 42 | +The `aiChatBackendPlugin()` requires a `model` parameter (from AI SDK) and accepts optional hooks for customizing behavior (authorization, logging, etc.). |
| 43 | + |
| 44 | +<Callout type="info"> |
| 45 | +**Model Configuration:** You can use any model from the AI SDK, including OpenAI, Anthropic, Google, and more. Make sure to install the corresponding provider package (e.g., `@ai-sdk/openai`) and set up your API keys in environment variables. |
| 46 | +</Callout> |
| 47 | + |
| 48 | +### 2. Add Plugin to Client |
| 49 | + |
| 50 | +Register the AI Chat client plugin in your `better-stack-client.tsx` file: |
| 51 | + |
| 52 | +```tsx title="lib/better-stack-client.tsx" |
| 53 | +import { createStackClient } from "@btst/stack/client" |
| 54 | +import { aiChatClientPlugin } from "@btst/stack/plugins/ai-chat/client" |
| 55 | + |
| 56 | +const getBaseURL = () => |
| 57 | + typeof window !== 'undefined' |
| 58 | + ? (process.env.NEXT_PUBLIC_BASE_URL || window.location.origin) |
| 59 | + : (process.env.BASE_URL || "http://localhost:3000") |
| 60 | + |
| 61 | +export const getStackClient = (queryClient: QueryClient) => { |
| 62 | + const baseURL = getBaseURL() |
| 63 | + return createStackClient({ |
| 64 | + plugins: { |
| 65 | + aiChat: aiChatClientPlugin({ |
| 66 | + apiBaseURL: baseURL, |
| 67 | + apiBasePath: "/api/data", |
| 68 | + }) |
| 69 | + } |
| 70 | + }) |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +**Required configuration:** |
| 75 | +- `apiBaseURL`: Base URL for API calls |
| 76 | +- `apiBasePath`: Path where your API is mounted (e.g., `/api/data`) |
| 77 | + |
| 78 | +### 3. Generate Database Schema |
| 79 | + |
| 80 | +After adding the plugin, generate your database schema using the CLI: |
| 81 | + |
| 82 | +```bash |
| 83 | +npx @btst/cli generate --orm prisma --config lib/better-stack.ts |
| 84 | +``` |
| 85 | + |
| 86 | +This will create the necessary database tables for conversations and messages. Run migrations as needed for your ORM. |
| 87 | + |
| 88 | +For more details on the CLI and all available options, see the [CLI documentation](/cli). |
| 89 | + |
| 90 | +## Usage |
| 91 | + |
| 92 | +The AI Chat plugin provides two routes: |
| 93 | + |
| 94 | +- `/chat` - Start a new conversation |
| 95 | +- `/chat/:id` - Resume an existing conversation |
| 96 | + |
| 97 | +The plugin automatically handles: |
| 98 | +- Creating and managing conversations |
| 99 | +- Saving messages to the database |
| 100 | +- Streaming AI responses in real-time |
| 101 | +- Conversation history persistence |
| 102 | + |
| 103 | +## Customization |
| 104 | + |
| 105 | +### Backend Hooks |
| 106 | + |
| 107 | +Customize backend behavior with optional hooks: |
| 108 | + |
| 109 | +<AutoTypeTable path="../packages/better-stack/src/plugins/ai-chat/api/plugin.ts" name="AiChatBackendHooks" /> |
| 110 | + |
| 111 | +**Example usage:** |
| 112 | + |
| 113 | +```ts title="lib/better-stack.ts" |
| 114 | +import { aiChatBackendPlugin, type AiChatBackendHooks } from "@btst/stack/plugins/ai-chat/api" |
| 115 | + |
| 116 | +const chatHooks: AiChatBackendHooks = { |
| 117 | + onBeforeChat: async (messages, context) => { |
| 118 | + // Add authorization logic |
| 119 | + const authHeader = context.headers?.get("authorization") |
| 120 | + if (!authHeader) { |
| 121 | + return false // Deny access |
| 122 | + } |
| 123 | + return true |
| 124 | + }, |
| 125 | + onAfterChat: async (conversationId, messages, context) => { |
| 126 | + // Log conversation or trigger webhooks |
| 127 | + console.log("Chat completed:", conversationId) |
| 128 | + }, |
| 129 | +} |
| 130 | + |
| 131 | +const { handler, dbSchema } = betterStack({ |
| 132 | + plugins: { |
| 133 | + aiChat: aiChatBackendPlugin({ |
| 134 | + model: openai("gpt-4o"), |
| 135 | + hooks: chatHooks |
| 136 | + }) |
| 137 | + }, |
| 138 | + // ... |
| 139 | +}) |
| 140 | +``` |
| 141 | + |
| 142 | +### Model Configuration |
| 143 | + |
| 144 | +You can configure different models and tools: |
| 145 | + |
| 146 | +```ts title="lib/better-stack.ts" |
| 147 | +import { openai } from "@ai-sdk/openai" |
| 148 | +import { anthropic } from "@ai-sdk/anthropic" |
| 149 | + |
| 150 | +// Use OpenAI |
| 151 | +aiChat: aiChatBackendPlugin({ |
| 152 | + model: openai("gpt-4o"), |
| 153 | +}) |
| 154 | + |
| 155 | +// Or use Anthropic |
| 156 | +aiChat: aiChatBackendPlugin({ |
| 157 | + model: anthropic("claude-3-5-sonnet-20241022"), |
| 158 | +}) |
| 159 | + |
| 160 | +// With tools (if your model supports it) |
| 161 | +aiChat: aiChatBackendPlugin({ |
| 162 | + model: openai("gpt-4o"), |
| 163 | + // Tools configuration would go here if supported |
| 164 | +}) |
| 165 | +``` |
| 166 | + |
| 167 | +## API Endpoints |
| 168 | + |
| 169 | +The plugin provides the following endpoints: |
| 170 | + |
| 171 | +- `POST /api/data/chat` - Send a message and receive streaming response |
| 172 | +- `GET /api/data/conversations` - List all conversations |
| 173 | +- `GET /api/data/conversations/:id` - Get a conversation with messages |
| 174 | +- `POST /api/data/conversations` - Create a new conversation |
| 175 | +- `DELETE /api/data/conversations/:id` - Delete a conversation |
| 176 | + |
| 177 | +## Client Components |
| 178 | + |
| 179 | +The plugin exports a `ChatInterface` component that you can use directly: |
| 180 | + |
| 181 | +```tsx |
| 182 | +import { ChatInterface } from "@btst/stack/plugins/ai-chat/client" |
| 183 | + |
| 184 | +export default function ChatPage() { |
| 185 | + return ( |
| 186 | + <ChatInterface |
| 187 | + apiPath="/api/data/chat" |
| 188 | + initialMessages={[]} |
| 189 | + /> |
| 190 | + ) |
| 191 | +} |
| 192 | +``` |
| 193 | + |
| 194 | +## Features |
| 195 | + |
| 196 | +- **Streaming Responses**: Real-time streaming of AI responses using AI SDK v5 |
| 197 | +- **Conversation History**: Automatic persistence of conversations and messages |
| 198 | +- **Customizable Models**: Use any LanguageModel from the AI SDK |
| 199 | +- **Authorization Hooks**: Add custom authentication and authorization logic |
| 200 | +- **Type-Safe**: Full TypeScript support with proper types from AI SDK |
| 201 | + |
0 commit comments