Devic UI Integration Guide

This guide explains how to integrate the @devicai/ui library into your React application to add AI assistant chat capabilities.

Prerequisites

• Node.js 20+
• React 17+ application
• Devic API key (obtain from Devic dashboard)

Installation

npm install @devicai/ui
# or
yarn add @devicai/ui
# or
pnpm add @devicai/ui

Basic Integration

Step 1: Import Styles

Add the CSS import to your application entry point:

// App.tsx or index.tsx
import '@devicai/ui/styles.css';

Step 2: Wrap Your App with DevicProvider

import { DevicProvider } from '@devicai/ui';

function App() {
  return (
    <DevicProvider
      apiKey="your-devic-api-key"
      baseUrl="https://api.devic.ai"  // Optional, defaults to this
    >
      <YourApp />
    </DevicProvider>
  );
}

Step 3: Add ChatDrawer Component

import { ChatDrawer } from '@devicai/ui';

function YourApp() {
  return (
    <div>
      {/* Your app content */}

      <ChatDrawer
        assistantId="your-assistant-identifier"
        options={{
          position: 'right',
          welcomeMessage: 'Hello! How can I help you today?',
          suggestedMessages: [
            'Help me get started',
            'What can you do?',
          ],
        }}
      />
    </div>
  );
}

Multi-Tenant Integration

For SaaS applications with multiple tenants:

<DevicProvider
  apiKey="your-api-key"
  tenantId="global-tenant-id"
  tenantMetadata={{ organizationId: 'org-123' }}
>
  <ChatDrawer
    assistantId="support-assistant"
    tenantId="specific-tenant-override"  // Overrides provider
    tenantMetadata={{
      userId: 'user-456',
      plan: 'enterprise'
    }}
  />
</DevicProvider>

Client-Side Tools (Model Interface Protocol)

Enable the assistant to call functions in your application:

import { ChatDrawer, ModelInterfaceTool } from '@devicai/ui';

// Define client-side tools
const tools: ModelInterfaceTool[] = [
  {
    toolName: 'get_user_location',
    schema: {
      type: 'function',
      function: {
        name: 'get_user_location',
        description: 'Get the current user geographic location',
        parameters: {
          type: 'object',
          properties: {},
        },
      },
    },
    callback: async () => {
      return new Promise((resolve, reject) => {
        navigator.geolocation.getCurrentPosition(
          (pos) => resolve({
            latitude: pos.coords.latitude,
            longitude: pos.coords.longitude,
          }),
          (err) => reject(new Error(err.message))
        );
      });
    },
  },
  {
    toolName: 'get_current_page',
    schema: {
      type: 'function',
      function: {
        name: 'get_current_page',
        description: 'Get the current page URL and title',
        parameters: {
          type: 'object',
          properties: {},
        },
      },
    },
    callback: async () => ({
      url: window.location.href,
      title: document.title,
      pathname: window.location.pathname,
    }),
  },
  {
    toolName: 'navigate_to_page',
    schema: {
      type: 'function',
      function: {
        name: 'navigate_to_page',
        description: 'Navigate the user to a specific page',
        parameters: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'The path to navigate to',
            },
          },
          required: ['path'],
        },
      },
    },
    callback: async ({ path }) => {
      window.location.href = path;
      return { success: true, navigatedTo: path };
    },
  },
];

function App() {
  return (
    <ChatDrawer
      assistantId="my-assistant"
      modelInterfaceTools={tools}
      onToolCall={(toolName, params) => {
        console.log(`Tool called: ${toolName}`, params);
      }}
    />
  );
}

Custom Chat UI with Hooks

Build a completely custom chat interface:

import { useDevicChat } from '@devicai/ui';

function CustomChat() {
  const {
    messages,
    isLoading,
    status,
    error,
    sendMessage,
    clearChat,
  } = useDevicChat({
    assistantId: 'my-assistant',
    onMessageReceived: (message) => {
      console.log('New message:', message);
    },
    onError: (error) => {
      console.error('Chat error:', error);
    },
  });

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const message = formData.get('message') as string;
    if (message.trim()) {
      sendMessage(message);
      e.currentTarget.reset();
    }
  };

  return (
    <div className="custom-chat">
      <div className="messages">
        {messages.map((msg) => (
          <div key={msg.uid} className={`message ${msg.role}`}>
            <strong>{msg.role}:</strong>
            <p>{msg.content.message}</p>
          </div>
        ))}
        {isLoading && <div className="loading">Thinking...</div>}
        {error && <div className="error">{error.message}</div>}
      </div>

      <form onSubmit={handleSubmit}>
        <input
          name="message"
          placeholder="Type a message..."
          disabled={isLoading}
        />
        <button type="submit" disabled={isLoading}>
          Send
        </button>
      </form>

      <button onClick={clearChat}>Clear Chat</button>
    </div>
  );
}

File Uploads

Enable file attachments in chat:

<ChatDrawer
  assistantId="document-assistant"
  options={{
    enableFileUploads: true,
    allowedFileTypes: {
      images: true,
      documents: true,
      audio: false,
      video: false,
    },
    maxFileSize: 10 * 1024 * 1024, // 10MB
  }}
/>

Display Modes

ChatDrawer supports two display modes via the mode prop:

Drawer Mode (default)

Renders as an overlay panel with a floating trigger button. Can be toggled open/closed.

<ChatDrawer
  mode="drawer"
  assistantId="my-assistant"
  options={{
    position: 'right',
    defaultOpen: false,
    zIndex: 1000,
  }}
/>

Inline Mode

Renders embedded in the page layout, always visible, no trigger button or toggle behavior.

<ChatDrawer
  mode="inline"
  assistantId="my-assistant"
  options={{
    width: 400,
    borderRadius: 12,
  }}
/>

Resizable Drawer

Enable drag-to-resize with width constraints:

<ChatDrawer
  assistantId="my-assistant"
  options={{
    resizable: true,
    width: 400,
    minWidth: 300,
    maxWidth: 800,
    position: 'right', // resize handle appears on the opposite edge
  }}
/>

Custom Rendering

Custom Loading Indicator

<ChatDrawer
  assistantId="my-assistant"
  options={{
    loadingIndicator: <MySpinner />,
  }}
/>

Custom Send Button

The click handler is managed by an overlay, so the node doesn’t need to handle click events.

<ChatDrawer
  assistantId="my-assistant"
  options={{
    sendButtonContent: <MyCustomIcon />,
  }}
/>

Custom Tool Renderers

Replace the default tool call summary with custom UI per tool name:

<ChatDrawer
  assistantId="my-assistant"
  options={{
    toolRenderers: {
      search_products: (input, output) => (
        <ProductGrid products={output.results} query={input.query} />
      ),
    },
    toolIcons: {
      search_products: <SearchIcon />,
    },
  }}
/>

Theming

Using Props

All color and typography properties can be set via options:

<ChatDrawer
  assistantId="my-assistant"
  options={{
    color: '#6366f1',                    // Primary color
    backgroundColor: '#ffffff',          // Drawer background
    textColor: '#1e293b',               // Text color
    secondaryBackgroundColor: '#f8fafc', // Input/selector background
    borderColor: '#e2e8f0',             // Border color
    userBubbleColor: '#6366f1',         // User message bubble
    userBubbleTextColor: '#ffffff',     // User message text
    assistantBubbleColor: '#f1f5f9',    // Assistant message bubble
    assistantBubbleTextColor: '#1e293b',// Assistant message text
    sendButtonColor: '#6366f1',         // Send button background
    fontFamily: '"Inter", sans-serif',  // Font override
  }}
/>

Using CSS Variables

Override the default theme by setting CSS variables:

/* your-styles.css */
:root {
  --devic-primary: #6366f1;        /* Primary color */
  --devic-primary-hover: #4f46e5;  /* Primary hover */
  --devic-primary-light: #eef2ff;  /* Light primary background */
  --devic-bg: #ffffff;             /* Background */
  --devic-bg-secondary: #f8fafc;   /* Secondary background */
  --devic-text: #1e293b;           /* Text color */
  --devic-text-secondary: #64748b; /* Secondary text */
  --devic-text-muted: #94a3b8;     /* Muted text */
  --devic-border: #e2e8f0;         /* Border color */
  --devic-shadow: 0 10px 40px rgba(0, 0, 0, 0.1);
  --devic-radius: 12px;            /* Border radius */
  --devic-radius-sm: 6px;
  --devic-radius-lg: 20px;
}

Using the color Option

Quick color customization:

<ChatDrawer
  assistantId="my-assistant"
  options={{
    color: '#6366f1', // Sets primary color
  }}
/>

Controlled Mode

Control the drawer state externally:

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>
        Open Chat
      </button>

      <ChatDrawer
        assistantId="my-assistant"
        isOpen={isOpen}
        onOpen={() => setIsOpen(true)}
        onClose={() => setIsOpen(false)}
      />
    </>
  );
}

Continuing Existing Conversations

Load and continue a previous chat:

function App() {
  // Get chatUid from URL, localStorage, or your backend
  const existingChatUid = 'previous-chat-uid';

  return (
    <ChatDrawer
      assistantId="my-assistant"
      chatUid={existingChatUid}
      onChatCreated={(newChatUid) => {
        // Save the new chat UID for future reference
        localStorage.setItem('lastChatUid', newChatUid);
      }}
    />
  );
}

Event Callbacks

Handle various chat events:

<ChatDrawer
  assistantId="my-assistant"
  onMessageSent={(message) => {
    // Track user messages
    analytics.track('chat_message_sent', {
      messageLength: message.content.message?.length,
    });
  }}
  onMessageReceived={(message) => {
    // Track assistant responses
    analytics.track('chat_message_received', {
      hasToolCalls: !!message.tool_calls?.length,
    });
  }}
  onToolCall={(toolName, params) => {
    // Track tool usage
    analytics.track('chat_tool_called', { toolName });
  }}
  onError={(error) => {
    // Report errors
    errorReporting.capture(error);
  }}
  onChatCreated={(chatUid) => {
    // Store chat reference
    saveChatReference(chatUid);
  }}
  onOpen={() => {
    // Track drawer open
    analytics.track('chat_opened');
  }}
  onClose={() => {
    // Track drawer close
    analytics.track('chat_closed');
  }}
/>

API Client Direct Usage

For advanced use cases, use the API client directly:

import { DevicApiClient } from '@devicai/ui';

const client = new DevicApiClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.devic.ai',
});

// List available assistants
const assistants = await client.getAssistants();

// Send a message (async mode)
const { chatUid } = await client.sendMessageAsync('assistant-id', {
  message: 'Hello!',
  tenantId: 'tenant-123',
  metadata: { source: 'web-app' },
});

// Poll for response
const checkResponse = async () => {
  const result = await client.getRealtimeHistory('assistant-id', chatUid);

  if (result.status === 'completed') {
    return result.chatHistory;
  } else if (result.status === 'error') {
    throw new Error('Processing failed');
  }

  // Continue polling
  await new Promise(r => setTimeout(r, 1000));
  return checkResponse();
};

const messages = await checkResponse();

Server-Side Rendering (SSR)

The library is SSR-compatible. Ensure you only render the ChatDrawer on the client:

// Next.js example
import dynamic from 'next/dynamic';

const ChatDrawer = dynamic(
  () => import('@devicai/ui').then(mod => mod.ChatDrawer),
  { ssr: false }
);

function Page() {
  return (
    <div>
      <h1>My Page</h1>
      <ChatDrawer assistantId="my-assistant" />
    </div>
  );
}

TypeScript Support

All types are exported for TypeScript users:

import type {
  // Chat types
  ChatMessage,
  ChatDrawerProps,
  ChatDrawerOptions,
  ChatDrawerHandle,

  // AICommandBar types
  AICommandBarProps,
  AICommandBarOptions,
  AICommandBarHandle,
  AICommandBarCommand,
  CommandBarResult,
  ToolCallSummary,

  // AIGenerationButton types
  AIGenerationButtonProps,
  AIGenerationButtonOptions,
  AIGenerationButtonHandle,
  AIGenerationButtonMode,
  GenerationResult,

  // Tool types
  ModelInterfaceTool,
  ModelInterfaceToolSchema,

  // Hook types
  UseDevicChatOptions,
  UseDevicChatResult,

  // API types
  RealtimeChatHistory,
  AssistantSpecialization,

  // Feedback types
  FeedbackSubmission,
  FeedbackEntry,
  FeedbackTheme,
} from '@devicai/ui';

// Use types in your code
const chatOptions: ChatDrawerOptions = {
  position: 'right',
  width: 400,
  welcomeMessage: 'Hello!',
};

const commandBarOptions: AICommandBarOptions = {
  shortcut: 'cmd+k',
  placeholder: 'Ask AI...',
};

const generationOptions: AIGenerationButtonOptions = {
  mode: 'modal',
  modalTitle: 'Generate with AI',
};

const handleMessage = (message: ChatMessage) => {
  console.log(message.content.message);
};

const handleCommandResult = (result: CommandBarResult) => {
  console.log('Chat UID:', result.chatUid);
  console.log('Tool calls:', result.toolCalls.length);
  console.log('Response:', result.message.content);
};

const handleGenerationResult = (result: GenerationResult) => {
  console.log('Generated content:', result.message.content.message);
  console.log('Tool calls executed:', result.toolCalls);
};

ChatDrawer Props Reference

ChatDrawerOptions Reference

Message Feedback

Both ChatDrawer and AICommandBar support message feedback (thumbs up/down with optional comments). Feedback is submitted to the Devic API and associated with the chat.

ChatDrawer Feedback

Feedback buttons appear on assistant messages by default. Users can click thumbs up/down and optionally add a comment via a modal.

<ChatDrawer
  assistantId="my-assistant"
  options={{
    showFeedback: true, // default: true
  }}
/>

AICommandBar Feedback

When showResultCard is enabled, feedback buttons appear below the response. The feedback UI automatically adapts to the command bar’s theme.

<AICommandBar
  assistantId="my-assistant"
  options={{
    showResultCard: true,
    // Feedback inherits theme from these options:
    backgroundColor: '#1f2937',
    textColor: '#f9fafb',
    borderColor: '#374151',
  }}
/>

Feedback Theming

The feedback modal and action buttons automatically inherit theme colors from the parent component. For custom implementations, you can pass a FeedbackTheme object:

interface FeedbackTheme {
  backgroundColor?: string;      // Modal background
  textColor?: string;            // Primary text
  textMutedColor?: string;       // Muted/secondary text
  secondaryBackgroundColor?: string; // Button backgrounds, hover states
  borderColor?: string;          // Modal borders
  primaryColor?: string;         // Primary action color
  primaryHoverColor?: string;    // Primary button hover
}

Feedback API

Feedback is automatically submitted to the Devic API using these endpoints:

• POST /api/v1/assistants/:identifier/chats/:chatUid/feedback – Submit feedback
• GET /api/v1/assistants/:identifier/chats/:chatUid/feedback – Get feedback entries

You can also use the API client directly:

import { DevicApiClient, FeedbackSubmission } from '@devicai/ui';

const client = new DevicApiClient({ apiKey: 'your-api-key' });

// Submit feedback
const feedback: FeedbackSubmission = {
  messageId: 'message-uid',
  feedback: true,  // true = positive, false = negative
  feedbackComment: 'Very helpful response!',
  feedbackData: { category: 'accuracy' },
};

await client.submitChatFeedback('assistant-id', 'chat-uid', feedback);

// Get all feedback for a chat
const entries = await client.getChatFeedback('assistant-id', 'chat-uid');

Feedback Types

import type {
  FeedbackSubmission,
  FeedbackEntry,
  FeedbackTheme,
} from '@devicai/ui';

// Submission payload
interface FeedbackSubmission {
  messageId: string;
  feedback?: boolean;              // true = positive, false = negative
  feedbackComment?: string;        // Optional comment
  feedbackData?: Record<string, any>; // Custom metadata
}

// Response from API
interface FeedbackEntry {
  _id: string;
  requestId: string;
  chatUID?: string;
  feedback?: boolean;
  feedbackComment?: string;
  feedbackData?: Record<string, any>;
  creationTimestamp: string;
  lastEditTimestamp?: string;
}

AICommandBar Component

A floating command bar (similar to Spotlight/Command Palette) for quick AI interactions. It provides a minimal input interface that processes messages, shows tool execution progress, and displays results in a compact card.

Basic Usage

import { AICommandBar } from '@devicai/ui';

function App() {
  return (
    <AICommandBar
      assistantId="my-assistant"
      options={{
        placeholder: 'Ask AI...',
        shortcut: 'cmd+k',
      }}
      onResponse={({ message, toolCalls }) => {
        console.log('Response:', message.content);
      }}
    />
  );
}

Fixed Position with Keyboard Shortcut

<AICommandBar
  assistantId="support-assistant"
  options={{
    position: 'fixed',
    fixedPlacement: { bottom: 20, right: 20 },
    shortcut: 'cmd+j',
    placeholder: 'Ask AI about your data...',
    showShortcutHint: true,
  }}
/>

Integration with ChatDrawer

Hand off conversations to the full ChatDrawer after getting a quick answer:

import { useRef } from 'react';
import { AICommandBar, ChatDrawer, ChatDrawerHandle } from '@devicai/ui';

function App() {
  const drawerRef = useRef<ChatDrawerHandle>(null);

  return (
    <>
      <AICommandBar
        assistantId="my-assistant"
        onExecute="openDrawer"
        chatDrawerRef={drawerRef}
        options={{
          shortcut: 'cmd+k',
          showResultCard: false, // Don't show result since drawer opens
        }}
      />

      <ChatDrawer
        ref={drawerRef}
        assistantId="my-assistant"
      />
    </>
  );
}

Command History

Command history is enabled by default. Users can:

• Press Arrow Up/Down to navigate through previous prompts
• Use the /history command to see the history list
• Click on a history item to reuse it

<AICommandBar
  assistantId="my-assistant"
  options={{
    enableHistory: true,           // default: true
    maxHistoryItems: 50,           // default: 50
    historyStorageKey: 'my-app-command-history', // localStorage key
    showHistoryCommand: true,      // adds /history command
  }}
/>

Commands System

Define slash commands that trigger predefined messages:

<AICommandBar
  assistantId="my-assistant"
  options={{
    commands: [
      {
        keyword: 'summarize',
        description: 'Summarize the current page',
        message: 'Please summarize the content of this page.',
        icon: <SummarizeIcon />,
      },
      {
        keyword: 'translate',
        description: 'Translate selected text',
        message: 'Translate the following text to Spanish: ',
      },
      {
        keyword: 'explain',
        description: 'Explain like I\'m five',
        message: 'Explain this concept in simple terms: ',
      },
    ],
  }}
/>

When the user types /, a dropdown shows available commands. Arrow keys navigate, Enter selects, Tab autocompletes.

Custom Tool Rendering

Display tool calls with custom icons and renderers:

<AICommandBar
  assistantId="my-assistant"
  options={{
    toolIcons: {
      search_database: <DatabaseIcon />,
      fetch_weather: <WeatherIcon />,
    },
    toolRenderers: {
      search_database: (input, output) => (
        <div className="custom-result">
          Found {output.count} results for "{input.query}"
        </div>
      ),
    },
  }}
/>

Theming

<AICommandBar
  assistantId="my-assistant"
  options={{
    color: '#6366f1',              // Primary color (spinner, badges)
    backgroundColor: '#ffffff',    // Bar background
    textColor: '#1f2937',          // Text color
    borderColor: '#e5e7eb',        // Border color
    borderRadius: 12,              // Border radius (px or string)
    fontFamily: 'Inter, sans-serif',
    fontSize: 14,
    padding: '12px 16px',
    boxShadow: '0 4px 20px rgba(0, 0, 0, 0.1)',
    animationDuration: 200,        // ms
  }}
/>

Controlled Visibility

function App() {
  const [isVisible, setIsVisible] = useState(false);
  const commandBarRef = useRef<AICommandBarHandle>(null);

  return (
    <>
      <button onClick={() => commandBarRef.current?.toggle()}>
        Toggle Command Bar
      </button>

      <AICommandBar
        ref={commandBarRef}
        assistantId="my-assistant"
        isVisible={isVisible}
        onVisibilityChange={setIsVisible}
        onOpen={() => console.log('Opened')}
        onClose={() => console.log('Closed')}
      />
    </>
  );
}

Using the Hook Directly

For custom UI implementations:

import { useAICommandBar, formatShortcut } from '@devicai/ui';

function CustomCommandBar() {
  const {
    isVisible,
    open,
    close,
    toggle,
    inputValue,
    setInputValue,
    inputRef,
    focus,
    isProcessing,
    currentToolSummary,
    toolCalls,
    result,
    error,
    history,
    showingHistory,
    showingCommands,
    filteredCommands,
    submit,
    reset,
    handleKeyDown,
  } = useAICommandBar({
    assistantId: 'my-assistant',
    options: { shortcut: 'cmd+k' },
    onResponse: (result) => console.log(result),
  });

  if (!isVisible) return null;

  return (
    <div className="my-command-bar">
      {isProcessing ? (
        <span>{currentToolSummary || 'Processing...'}</span>
      ) : (
        <input
          ref={inputRef}
          value={inputValue}
          onChange={(e) => setInputValue(e.target.value)}
          onKeyDown={handleKeyDown}
          placeholder="Ask AI..."
        />
      )}
    </div>
  );
}

AICommandBar Props Reference

AICommandBarOptions Reference

AICommandBarHandle Reference

Methods exposed via ref:

AIGenerationButton Component

A button component for triggering AI generation with three configurable interaction modes. Useful for “Generate with AI” buttons in forms, editors, and other UI contexts.

Basic Usage

import { AIGenerationButton } from '@devicai/ui';

function App() {
  return (
    <AIGenerationButton
      assistantId="my-assistant"
      options={{
        mode: 'modal',
        modalTitle: 'Generate Content',
        placeholder: 'Describe what you want to generate...',
      }}
      onResponse={({ message }) => {
        console.log('Generated:', message.content.message);
      }}
    />
  );
}

Interaction Modes

Direct Mode

Sends a predefined prompt immediately when clicked. Best for specific, predetermined actions.

<AIGenerationButton
  assistantId="my-assistant"
  options={{
    mode: 'direct',
    prompt: 'Generate a product description based on the form data',
    label: 'Auto-Generate Description',
    loadingLabel: 'Generating...',
  }}
  onBeforeSend={(prompt) => {
    // Optionally modify the prompt before sending
    return `${prompt}\n\nProduct: ${productName}`;
  }}
  onResponse={({ message }) => setDescription(message.content.message)}
/>

Modal Mode (Default)

Opens a modal dialog for the user to enter a custom prompt.

<AIGenerationButton
  assistantId="my-assistant"
  options={{
    mode: 'modal',
    modalTitle: 'Generate with AI',
    modalDescription: 'Describe what you want and the AI will generate it for you.',
    placeholder: 'E.g., Create a function that validates email addresses...',
    confirmText: 'Generate',
    cancelText: 'Cancel',
  }}
  onResponse={({ message }) => {
    // Handle the generated content
    setCode(message.content.message);
  }}
/>

Tooltip Mode

Shows a compact inline input next to the button. Good for quick prompts without modal interruption.

<AIGenerationButton
  assistantId="my-assistant"
  options={{
    mode: 'tooltip',
    tooltipPlacement: 'bottom', // 'top' | 'bottom' | 'left' | 'right'
    tooltipWidth: 350,
    placeholder: 'What should I generate?',
  }}
  onResponse={handleGeneration}
/>

Button Styling

<AIGenerationButton
  assistantId="my-assistant"
  options={{
    // Button variant
    variant: 'primary', // 'primary' | 'secondary' | 'outline' | 'ghost'

    // Button size
    size: 'medium', // 'small' | 'medium' | 'large'

    // Label and icon
    label: 'Generate with AI',
    hideLabel: false, // Set true for icon-only button
    icon: <CustomSparkleIcon />, // Custom icon
    hideIcon: false,

    // Loading state
    loadingLabel: 'Generating...',
  }}
/>

Theming

<AIGenerationButton
  assistantId="my-assistant"
  options={{
    color: '#6366f1',           // Primary color
    backgroundColor: '#ffffff',  // Button background (for secondary/outline variants)
    textColor: '#1f2937',        // Text color
    borderColor: '#e5e7eb',      // Border color
    borderRadius: 8,             // Border radius
    fontFamily: 'Inter, sans-serif',
    fontSize: 14,
    zIndex: 10000,               // Z-index for modal/tooltip
    animationDuration: 200,      // Animation duration in ms
  }}
/>

Custom Button Content

Use children to completely customize the button appearance:

<AIGenerationButton
  assistantId="my-assistant"
  options={{ mode: 'modal' }}
  onResponse={handleResponse}
>
  <span className="my-custom-button">
    <SparkleIcon /> Generate Code
  </span>
</AIGenerationButton>

Programmatic Control

Use ref to control the component programmatically:

import { useRef } from 'react';
import { AIGenerationButton, AIGenerationButtonHandle } from '@devicai/ui';

function Editor() {
  const buttonRef = useRef<AIGenerationButtonHandle>(null);

  const handleKeyboardShortcut = (e: KeyboardEvent) => {
    if (e.metaKey && e.key === 'g') {
      buttonRef.current?.open(); // Open modal/tooltip
    }
  };

  const generateDirectly = async () => {
    const result = await buttonRef.current?.generate('Generate a summary');
    if (result) {
      console.log('Generated:', result.message.content.message);
    }
  };

  return (
    <AIGenerationButton
      ref={buttonRef}
      assistantId="my-assistant"
      options={{ mode: 'modal' }}
      onResponse={handleResponse}
    />
  );
}

Using the Hook Directly

For completely custom UI implementations:

import { useAIGenerationButton } from '@devicai/ui';

function CustomGenerateButton() {
  const {
    isOpen,
    isProcessing,
    inputValue,
    setInputValue,
    error,
    result,
    inputRef,
    open,
    close,
    generate,
    reset,
    handleKeyDown,
  } = useAIGenerationButton({
    assistantId: 'my-assistant',
    onResponse: (result) => console.log('Generated:', result),
    onError: (error) => console.error('Error:', error),
  });

  return (
    <div>
      <button onClick={() => open()}>
        {isProcessing ? 'Generating...' : 'Generate'}
      </button>

      {isOpen && (
        <div className="custom-modal">
          <textarea
            ref={inputRef}
            value={inputValue}
            onChange={(e) => setInputValue(e.target.value)}
            onKeyDown={handleKeyDown}
            placeholder="Describe what to generate..."
          />
          <button onClick={() => generate()} disabled={isProcessing}>
            {isProcessing ? 'Working...' : 'Generate'}
          </button>
          <button onClick={close}>Cancel</button>
          {error && <p className="error">{error.message}</p>}
        </div>
      )}
    </div>
  );
}

AIGenerationButton Props Reference

AIGenerationButtonOptions Reference

AIGenerationButtonHandle Reference

Methods exposed via ref:

Troubleshooting

Chat not loading

1. Verify your API key is correct
2. Check the browser console for errors
3. Ensure the assistant identifier exists

Styles not applied

1. Make sure you imported the CSS: import '@devicai/ui/styles.css'
2. Check for CSS conflicts with your application styles
3. Try increasing specificity or using CSS variables

Tools not being called

1. Verify the tool schema matches OpenAI function calling format
2. Check that toolName matches function.name in schema
3. Ensure the assistant has been configured to use client-side tools

File uploads not working

1. Enable file uploads in options: enableFileUploads: true
2. Check allowed file types configuration
3. Verify file size is within limits

Support

For issues and feature requests, visit the GitHub repository.