Merge pull request #1153 from objectstack-ai/copilot/refactor-chatbot-plugin-ai-sdui

Author: hotlong

CHANGELOG.md

@@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **AI SDUI Chatbot integration** (`@object-ui/plugin-chatbot`): Refactored chatbot plugin to support full AI streaming via `service-ai` backend and `vercel/ai` SDK (`@ai-sdk/react`). New `useObjectChat` composable hook wraps `@ai-sdk/react`'s `useChat` for SSE streaming, tool-calling, and production-grade chat. Auto-detects API mode (when `api` schema field is set) vs legacy local auto-response mode. ChatbotEnhanced component now supports stop, reload, error display, and streaming state indicators. 44 unit tests (19 new hook tests, 10 new streaming tests).
+
+- **New ChatbotSchema fields** (`@object-ui/types`): Extended `ChatbotSchema` with `api`, `conversationId`, `systemPrompt`, `model`, `streamingEnabled`, `headers`, `body`, `maxToolRoundtrips`, and `onError` fields for service-ai integration. Extended `ChatMessage` with `streaming`, `toolInvocations` fields and added `ChatToolInvocation` interface for tool-calling flows.
+
+- **New Storybook stories for AI chatbot** (`@object-ui/components`): Added `AIStreamingMode`, `AIWithSystemPrompt`, and `AIWithToolCalls` stories demonstrating the new AI SDUI chat modes alongside existing local/demo stories.
+
 - **Object Manager visual designer** (`@object-ui/plugin-designer`): Enterprise-grade object management interface for creating, editing, deleting, and configuring meta-object definitions. Uses standard ObjectGrid for the list view and ModalForm for create/edit operations. Features include property editing (name, label, plural label, description, icon, group, sort order, enabled toggle), object relationship display, search/filter, system object protection, confirm dialogs for destructive actions, and read-only mode. 18 unit tests.
 
 - **Field Designer visual designer** (`@object-ui/plugin-designer`): Enterprise-grade field configuration wizard supporting 27 field types with full CRUD operations. Uses standard ObjectGrid for the list view with a specialized FieldEditor panel for advanced type-specific properties. Features include uniqueness constraints, default values, picklist/option set management, read-only, hidden, validation rules (min/max/length/pattern/custom), external ID, history tracking, and database indexing. Type-specific editors for lookup references, formula expressions, and select options. Field type filtering, search, system field protection, and read-only mode. 22 unit tests.

ROADMAP.md

@@ -5,7 +5,7 @@
 > **Spec Version:** @objectstack/spec v3.3.0
 > **Client Version:** @objectstack/client v3.3.0
 > **Target UX Benchmark:** 🎯 Airtable parity
-> **Current Priority:** AppShell Navigation · Designer Interaction · **View Config Live Preview Sync ✅** · Dashboard Config Panel · Airtable UX Polish · **Flow Designer ✅** · **App Creation & Editing Flow ✅** · **System Settings & App Management ✅** · **Right-Side Visual Editor Drawer ✅** · **Object Manager & Field Designer ✅**
+> **Current Priority:** AppShell Navigation · Designer Interaction · **View Config Live Preview Sync ✅** · Dashboard Config Panel · Airtable UX Polish · **Flow Designer ✅** · **App Creation & Editing Flow ✅** · **System Settings & App Management ✅** · **Right-Side Visual Editor Drawer ✅** · **Object Manager & Field Designer ✅** · **AI SDUI Chatbot (service-ai + vercel/ai) ✅**
 
 ---
 

content/docs/plugins/plugin-chatbot.mdx

@@ -170,7 +170,17 @@ const schema = {
   autoResponseText?: string,
   autoResponseDelay?: number,
   onSend?: (content: string, messages: ChatMessage[]) => void,
-  className?: string
+  className?: string,
+  // AI / service-ai integration fields
+  api?: string,
+  conversationId?: string,
+  systemPrompt?: string,
+  model?: string,
+  streamingEnabled?: boolean,
+  headers?: Record<string, string>,
+  body?: Record<string, unknown>,
+  maxToolRoundtrips?: number,
+  onError?: (error: Error) => void,
 }
 ```
 
@@ -179,11 +189,12 @@ const schema = {
 ```plaintext
 {
   id: string,
-  role: 'user' | 'assistant' | 'system',
+  role: 'user' | 'assistant' | 'system' | 'tool',
   content: string,
-  timestamp?: string,
-  avatar?: string,
-  avatarFallback?: string
+  timestamp?: string | Date,
+  metadata?: any,
+  streaming?: boolean,
+  toolInvocations?: ChatToolInvocation[],
 }
 ```
 
@@ -200,11 +211,53 @@ const schema = {
 | `assistantAvatarUrl` | string | - | URL for assistant avatar image |
 | `assistantAvatarFallback` | string | `'AI'` | Fallback text for assistant avatar |
 | `maxHeight` | string | `'500px'` | Maximum chat container height |
-| `autoResponse` | boolean | `false` | Enable auto-response (demo mode) |
+| `autoResponse` | boolean | `false` | Enable auto-response (demo mode, ignored when `api` is set) |
 | `autoResponseText` | string | - | Text for auto-response |
 | `autoResponseDelay` | number | `1000` | Delay before auto-response (ms) |
 | `onSend` | function | - | Callback when message is sent |
 | `className` | string | `''` | Additional Tailwind CSS classes |
+| `api` | string | - | Backend SSE endpoint (e.g., `/api/v1/ai/chat`). Enables AI streaming mode |
+| `conversationId` | string | - | Multi-turn conversation identifier |
+| `systemPrompt` | string | - | System prompt to configure assistant behavior |
+| `model` | string | - | AI model identifier (e.g., `gpt-4o`) |
+| `streamingEnabled` | boolean | `true` | Enable SSE streaming for AI responses |
+| `headers` | object | - | Additional headers for API requests |
+| `body` | object | - | Additional body params for API requests |
+| `maxToolRoundtrips` | number | `5` | Max tool-calling round-trips per message |
+| `onError` | function | - | Error callback for streaming/API errors |
+
+## Operating Modes
+
+The chatbot supports two modes, automatically selected based on the `api` field:
+
+### Local/Demo Mode (default)
+
+When `api` is not set, the chatbot operates in local mode with optional auto-response:
+
+```tsx
+const schema = {
+  type: 'chatbot',
+  messages: [...],
+  autoResponse: true,
+  autoResponseText: 'Thanks!',
+  autoResponseDelay: 1000,
+};
+```
+
+### AI Streaming Mode (service-ai)
+
+When `api` is set, the chatbot uses `@ai-sdk/react` for real SSE streaming:
+
+```tsx
+const schema = {
+  type: 'chatbot',
+  api: '/api/v1/ai/chat',
+  model: 'gpt-4o',
+  systemPrompt: 'You are a helpful assistant.',
+  streamingEnabled: true,
+  messages: [],
+};
+```
 
 ## Message Roles
 
@@ -246,6 +299,27 @@ System messages appear centered with muted styling:
 }
 ```
 
+### Tool Messages (AI Mode)
+
+Tool messages represent results from tool invocations during AI streaming. They are generated automatically by the vercel/ai SDK when the backend performs tool calls (e.g., fetching weather, querying a database). The SDK may emit `role: 'tool'` messages as well as populate the assistant message's `toolInvocations` array. In the current chat UI, any non-`user` role (including `tool`) is rendered as an assistant bubble, so if you do not want raw tool messages to appear you should filter them out before rendering and instead rely on the assistant message's `toolInvocations`:
+
+```tsx
+{
+  id: '4',
+  role: 'assistant',
+  content: 'The weather in SF is 68°F.',
+  toolInvocations: [
+    {
+      toolCallId: 'tc-1',
+      toolName: 'getWeather',
+      args: { city: 'San Francisco' },
+      result: { temp: 68, condition: 'Sunny' },
+      state: 'result',
+    }
+  ]
+}
+```
+
 ## Examples
 
 ### Simple AI Chat
@@ -445,8 +519,10 @@ const schema = {
 ## TypeScript Support
 
 ```plaintext
-import type { ChatbotSchema, ChatMessage } from '@object-ui/types'
+import type { ChatbotSchema, ChatMessage, ChatToolInvocation } from '@object-ui/types'
+import { useObjectChat } from '@object-ui/plugin-chatbot'
 
+// Basic messages
 const messages: ChatMessage[] = [
   {
     id: '1',
@@ -455,12 +531,24 @@ const messages: ChatMessage[] = [
   }
 ]
 
-const chatbotSchema: ChatbotSchema = {
+// Local/demo mode
+const demoSchema: ChatbotSchema = {
   type: 'chatbot',
   messages,
   placeholder: 'Type here...',
   showTimestamp: true
 }
+
+// AI streaming mode (service-ai)
+const aiSchema: ChatbotSchema = {
+  type: 'chatbot',
+  messages: [],
+  api: '/api/v1/ai/chat',
+  model: 'gpt-4o',
+  systemPrompt: 'You are a helpful assistant.',
+  streamingEnabled: true,
+  conversationId: 'conv-123',
+}
 ```
 
 ## Related Documentation

packages/components/src/stories-json/chatbot.stories.tsx

@@ -246,3 +246,104 @@ export const StreamingResponse: Story = {
     className: 'w-full max-w-2xl'
   } as any,
 };
+
+// ============================================================================
+// AI SDUI Mode Stories (service-ai integration)
+// ============================================================================
+
+/**
+ * AI Streaming Mode - demonstrates schema config for service-ai backend.
+ * In production, set `api` to your service-ai endpoint.
+ * Without a real backend, this falls back to local auto-response.
+ */
+export const AIStreamingMode: Story = {
+  render: renderStory,
+  args: {
+    type: 'chatbot',
+    messages: [
+      {
+        id: 'welcome',
+        role: 'assistant',
+        content: 'Hello! I\'m your AI assistant powered by service-ai. Ask me anything!',
+      }
+    ],
+    placeholder: 'Ask the AI assistant...',
+    enableMarkdown: true,
+    showTimestamp: false,
+    // AI SDUI fields — in production, set api to your endpoint:
+    // api: '/api/v1/ai/chat',
+    // model: 'gpt-4o',
+    // systemPrompt: 'You are a helpful assistant.',
+    // streamingEnabled: true,
+    // Fallback to auto-response for demo:
+    autoResponse: true,
+    autoResponseText: 'This is a demo response. In production, connect `api` to your service-ai endpoint for real streaming.',
+    autoResponseDelay: 800,
+    className: 'w-full max-w-2xl'
+  } as any,
+};
+
+/**
+ * AI Chat with system prompt and model config.
+ */
+export const AIWithSystemPrompt: Story = {
+  render: renderStory,
+  args: {
+    type: 'chatbot',
+    messages: [
+      {
+        id: 'system-1',
+        role: 'system',
+        content: 'You are a customer support agent for Acme Inc.',
+      },
+      {
+        id: 'welcome',
+        role: 'assistant',
+        content: 'Welcome to Acme Support! How can I help you today?',
+      }
+    ],
+    placeholder: 'Describe your issue...',
+    enableMarkdown: true,
+    showTimestamp: true,
+    systemPrompt: 'You are a customer support agent for Acme Inc. Be helpful and professional.',
+    model: 'gpt-4o',
+    autoResponse: true,
+    autoResponseText: 'Thank you for contacting Acme Support. I\'m looking into your request.',
+    autoResponseDelay: 1200,
+    className: 'w-full max-w-2xl'
+  } as any,
+};
+
+/**
+ * AI Chat including tool invocation metadata in messages.
+ */
+export const AIWithToolCalls: Story = {
+  render: renderStory,
+  args: {
+    type: 'chatbot',
+    messages: [
+      {
+        id: '1',
+        role: 'user',
+        content: 'What\'s the weather in San Francisco?',
+      },
+      {
+        id: '2',
+        role: 'assistant',
+        content: 'The weather in San Francisco is currently 68°F with partly cloudy skies.',
+        toolInvocations: [
+          {
+            toolCallId: 'tc-1',
+            toolName: 'getWeather',
+            args: { city: 'San Francisco' },
+            result: { temp: 68, condition: 'Partly cloudy' },
+            state: 'result',
+          }
+        ],
+      }
+    ],
+    placeholder: 'Ask about weather, stocks, or more...',
+    enableMarkdown: true,
+    className: 'w-full max-w-2xl'
+  } as any,
+};