syncfusion-javascript-ai-assistview

# Syncfusion JavaScript AI AssistView Component ## Overview The AI AssistView is an interactive chat component designed for building AI-powered conversational interfaces with support for prompts, responses, suggestions, custom toolbars, file attachments, speech features, and AI service integrations. The AI AssistView component provides: - **Prompt-Response System**: Display conversations with user prompts and AI responses - **AI Service Integration**: Built-in support for major AI providers (OpenAI, Gemini, Ollama, etc.) - **Toolbar Customization**: Header, footer, prompt, and response toolbars with custom items - **File Attachments**: Upload and attach files to prompts - **Speech Features**: Speech-to-text input and text-to-speech output - **Custom Views**: Multiple view modes (Assist, Custom) with templates - **Templates**: Customize banner, prompt items, response items, suggestions, and footer - **Markdown Support**: Automatic markdown-to-HTML conversion for responses - **Streaming Responses**: Real-time response streaming for AI outputs - **Chain of Thoughts**: Collapsible thinking/reasoning blocks with staged, streamable status updates via the `AssistThinking` module - **Generative UI**: Render interactive tools and dynamic UI (cards, charts, forms, custom components) within AI responses via `blocks` and `registerToolUI` - **Regenerate Responses**: Request alternative AI responses for an existing prompt via the built-in `e-assist-regenerate` toolbar item, with automatic previous/next navigation between saved responses (`regeneratedResponses`) - **Telemetry**: Built-in telemetry that tracks AI interaction metrics (`status`, `duration`, `toolCalls`, `streamingChunks`, `model`, `inputTokens`, `outputTokens`, `totalTokens`, `reasoningTokens`, `cachedInputTokens`, plus custom attributes) and renders a per-response toolbar button with a hover tooltip report, fully configurable via `telemetrySettings` (`enable`, `metrics`, `beforeReport`) - **Mentions**: Insert mention triggers in the prompt editor (e.g. `@` or `/`) backed by a local or remote data source (`DataManager`), with configurable fields, `query`, `filterType` (`Contains`/`StartsWith`/`EndsWith`), match highlighting, popup dimensions, and custom item/display/no-records templates; select an item via the `mentionSelect` event - **Response Animation**: Custom loading indicator or animation shown while an AI response is being generated, configured via the `responseAnimationTemplate` property (string or function returning HTML), and visible until `addPromptResponse` is called and any `Promise` returned by `promptRequest` resolves - **Accessibility**: WCAG compliance with keyboard navigation and ARIA support --- ## Documentation and Navigation Guide ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) - Package installation and dependencies (`@syncfusion/ej2-interactive-chat`) - CSS imports and theme configuration - Basic AI AssistView initialization - First render with prompts and responses - `promptRequest` event handling for AI integration - Width, height, locale, and persistence configuration ### Assist View Configuration 📄 **Read:** [references/assist-view-configuration.md](references/assist-view-configuration.md) - Setting prompt text and placeholder (`prompt`, `promptPlaceholder`) - Prompt and response icon customization (`promptIconCss`, `responseIconCss`) - Prompt-response collection (`prompts` property with `PromptModel[]`) - Adding prompt suggestions (`promptSuggestions`, `promptSuggestionsHeader`) - Show/hide clear button and header (`showClearButton`, `showHeader`) - Enable scroll to bottom functionality (`enableScrollToBottom`) - Markdown response rendering with built-in converter - Response streaming (`enableStreaming`) ### AI Service Integrations 📄 **Read:** [references/ai-integrations.md](references/ai-integrations.md) - OpenAI and Azure OpenAI integration with API setup - Google Gemini integration and configuration - Ollama LLM local model integration - LiteLLM proxy service integration - MCP Server integration for Model Context Protocol - Custom AI service integration patterns - `promptRequest` event best practices - Error handling and response formatting ### Chain of Thoughts (Thinking Blocks) 📄 **Read:** [references/chain-of-thoughts.md](references/chain-of-thoughts.md) - Enabling reasoning visualization via the injectable `AssistThinking` module (`AIAssistView.Inject(AssistThinking)`) - Response block types: `thinking`, `text`, `tool` blocks within the `blocks` array - Configuring thinking blocks (`blockType`, `title`, `content`, `isActive`, `collapsed`, `collapsible`, `stages`) - Adding reasoning stages (`ThinkingStage`) with Timeline-based rendering - Stage status indicators (`completed`, `inprogress`, `failed`) for streaming reasoning progress - Inline clickable context badges (`editableContext`, `ThinkingContextItem`) with `{index}` placeholders - Handling the `editableContextClicked` event - Custom thinking block rendering (`blockTemplate`) and stage item rendering (`itemTemplate`) ### Generative UI 📄 **Read:** [references/generative-ui.md](references/generative-ui.md) - Registering custom tools with `registerToolUI({ toolName, template, handler? })` - Configuring tool templates (string or function) and interactivity handlers - Adding `tool` blocks (`blockType: 'tool'`, `toolName`, `props`) to responses via `addPromptResponse` - Mixing `text` and `tool` blocks in a single response - Configuring an AI service's system prompt to return structured `blocks` JSON for generative UI - Multi-step generative flows: capturing tool state and triggering follow-up responses with `executePrompt` ### Toolbar Configuration 📄 **Read:** [references/toolbar-configuration.md](references/toolbar-configuration.md) - Header toolbar configuration (`toolbarSettings`) - Footer toolbar setup (`footerToolbarSettings`, toolbar positioning: Inline/Bottom) - Response toolbar items (`responseToolbarSettings`, like/dislike/copy/refresh) - Prompt toolbar items (`promptToolbarSettings`) - Custom toolbar items (text, icons, tooltips, alignment, templates) - Toolbar item click events (`ToolbarItemClickedEventArgs`) - Built-in toolbar items (send, attachment) - Regenerating responses via the built-in `e-assist-regenerate` response toolbar item - Pre-loading alternate responses with `regeneratedResponses` (`PromptModel`) and the automatic previous/next navigation UI ### Custom Views 📄 **Read:** [references/custom-views.md](references/custom-views.md) - Adding custom views (`views` property with `AssistViewModel[]`) - View types: Assist vs Custom (`AssistViewType` enum) - Setting view name and icon (`name`, `iconCss`) - View templates (`viewTemplate` for custom content) - Active view management (`activeView` property) - Switching between views programmatically ### Templates 📄 **Read:** [references/templates.md](references/templates.md) - Banner template for welcome messages (`bannerTemplate`) - Prompt item template customization (`promptItemTemplate`) - Response item template formatting (`responseItemTemplate`) - Prompt suggestion item template (`promptSuggestionItemTemplate`) - Footer template for custom input areas (`footerTemplate`) - Template context and data binding - Template customization examples ### File Attachments 📄 **Read:** [references/file-attachments.md](references/file-attachments.md) - Enabling attachments (`enableAttachments`) - Attachment settings (`attachmentSettings` with allowed types, size limits, max count) - Upload configuration (saveUrl, removeUrl) - Attached files in prompts (`PromptModel.attachedFiles`) - Attachment events (beforeUpload, success, failure, removed) - File preview and click handling - Custom attachment templates (attachmentTemplate) ### Speech to Text 📄 **Read:** [references/speech-to-text.md](references/speech-to-text.md) - Speech-to-text configuration (`speechToTextSettings`) - Browser speech recognition setup - Language and locale settings - Button and tooltip customization - Interim results and transcript handling - Microphone permissions and error handling ### Text to Speech 📄 **Read:** [references/text-to-speech.md](references/text-to-speech.md) - Enabling built-in Text-to-Speech via the `e-assist-audio` response toolbar item - Speech synthesis configuration (`textToSpeechSettings`) - Customizing `language`, `speechPitch`, `speechRate`, `volume`, `voice`, and `inputText` - Reading AI responses aloud using the browser's `SpeechSynthesisUtterance` interface - Browser compatibility and feature detection ### Appearance Customization 📄 **Read:** [references/appearance.md](references/appearance.md) - CSS class customization (`cssClass`) - Width and height configuration - RTL support (`enableRtl`) - Theme customization with Syncfusion themes - Custom styling examples - Responsive design patterns ### Methods and Events 📄 **Read:** [references/methods-and-events.md](references/methods-and-events.md) - Methods: `addPromptResponse()` (with optional `TelemetryData` second argument), `executePrompt()`, `scrollToBottom()`, `refresh()` - Events: `created`, `promptRequest`, `promptChanged`, `stopRespondingClick` - Attachment events: `beforeAttachmentUpload`, `attachmentUploadSuccess`,`attachmentUploadFailure`, `attachmentRemoving` (pre-removal hook), `attachmentRemoved`, `attachmentClick` - Event args interfaces and usage patterns - Method usage examples ### Telemetry 📄 **Read:** [references/telemetry.md](references/telemetry.md) - Enabling telemetry via `telemetrySettings.enable` - Built-in per-response telemetry button (showing duration) and hover tooltip report - Configuring captured metrics with `telemetrySettings.metrics` and the `TelemetryMetric` type (`status`, `duration`, `toolCalls`, `streamingChunks`, `model`, `inputTokens`, `outputTokens`, `totalTokens`, `reasoningTokens`, `cachedInputTokens`); array order sets tooltip display order - Customizing or suppressing reports via the `telemetrySettings.beforeReport` event with `TelemetryReport` - Passing AI usage data via the `TelemetryData` parameter of `addPromptResponse` (`model`, `inputTokens`, `outputTokens`, `reasoningTokens`, `cachedInputTokens`, `customAttributes`) - Surfacing custom attributes (`region`, `tenant`, `sessionId`, `feature`, etc.) as their own rows in the tooltip - Key behaviors: turn tracking, disabled-state telemetry button, duration formatting, automatic `totalTokens`, metrics filter precedence, regenerate flow ### Mentions 📄 **Read:** [references/mentions.md](references/mentions.md) - Configuring mention trigger characters (`mentionChar`, e.g. `@` or `/`) via the `mentions` array - Data sources for mention items: local collections or `DataManager` (local/remote) - Field mappings (`fields.text`, `fields.value`, `fields.iconCss`) and additional data operations (`query`) - Filtering and matching: `filterType` (`Contains`/`StartsWith`/`EndsWith`) and `highlight` - Selected-mention display: `showMentionChar` and `displayTemplate` - Popup customization: `popupWidth`, `popupHeight`, `itemTemplate`, and `noRecordsTemplate` - Handling user selection through the `mentionSelect` event --- ## Quick Start ### Basic AI AssistView ```typescript import { AIAssistView, PromptRequestEventArgs } from '@syncfusion/ej2-interactive-chat'; import { enableRipple } from '@syncfusion/ej2-base'; enableRipple(true); // Initialize AI AssistView const aiAssistView: AIAssistView = new AIAssistView({ promptSuggestions: [ 'How do I get started?', 'What are the key features?' ], promptRequest: (args: PromptRequestEventArgs) => { // Handle prompt request - integrate with AI service here setTimeout(() => { const response = 'This is the AI response to: ' + args.prompt; aiAssistView.addPromptResponse(response); }, 1000); } }); // Render to DOM aiAssistView.appendTo('#aiAssistView'); ``` ### HTML Structure ```html <!DOCTYPE html> <html lang="en"> <head> <title>AI AssistView</title> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <!-- Syncfusion CSS --> <link href="https://cdn.syncfusion.com/ej2/32.1.19/fluent2.css" rel="stylesheet" /> </head> <body> <div id='container' style="height: 400px; width: 700px;"> <div id="aiAssistView"></div> </div> </body> </html> ``` ### CSS Imports ```css @import "../../node_modules/@syncfusion/ej2-fluent2-theme/styles/ai-assistview/index.css"; ``` --- ## Common Patterns ### Pattern 1: OpenAI Integration ```typescript const aiAssistView: AIAssistView = new AIAssistView({ promptSuggestions: ['Explain AI', 'Code example', 'Best practices'], promptRequest: async (args: PromptRequestEventArgs) => { try { const response = await fetch('https://api.openai.com/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${OPENAI_API_KEY}` }, body: JSON.stringify({ model: 'gpt-4', messages: [{ role: 'user', content: args.prompt }] }) }); const data = await response.json(); const aiResponse = data.choices[0].message.content; aiAssistView.addPromptResponse(aiResponse); } catch (error) { aiAssistView.addPromptResponse('Error: ' + error.message); } } }); ``` ### Pattern 2: Markdown Responses with Streaming ```typescript const aiAssistView: AIAssistView = new AIAssistView({ enableStreaming: true, promptRequest: (args: PromptRequestEventArgs) => { // Simulate streaming response const markdownResponse = `# Response\n\nThis is **bold** and *italic* text.\n\n- Item 1\n- Item 2\n\`\`\`javascript\nconst x = 10;\n\`\`\``; let index = 0; const interval = setInterval(() => { if (index < markdownResponse.length) { const chunk = markdownResponse.slice(0, index + 5); aiAssistView.addPromptResponse(chunk, false); index += 5; } else { clearInterval(interval); aiAssistView.addPromptResponse(markdownResponse, true); } }, 50); } }); ``` ### Pattern 3: Custom Toolbar with Actions ```typescript const aiAssistView: AIAssistView = new AIAssistView({ responseToolbarSettings: {