Generative Search Widget

The Generative Search widget provides an AI-powered chat interface for searching and analyzing AlphaSense content. Users can ask natural language questions and receive intelligent responses with document citations that can be clicked to view source documents.

Table of Contents

• Basic Usage
• Configuration Options
• Conversation Management
• Integration Patterns
• Error Handling

Basic Usage with CDN

Starting New Conversations with an initial prompt

<div id="generative-search" style="width: 100%; height: 600px;"></div> // target container for the widget

<script src="https://unpkg.com/@alphasense/embedded-widgets@latest/dist/index.min.js"></script>
<script>
  new AlphaSenseWidget({
    target: '#generative-search',
    widgetType: 'generativeSearch',
    generativeSearchParams: {
      initialPrompt: 'What are the latest earnings trends?'
    },
  }).init();
</script>

Starting New Conversations without an initial prompt

<div id="generative-search" style="width: 100%; height: 600px;"></div>
<script src="https://unpkg.com/@alphasense/embedded-widgets@latest/dist/index.min.js"></script>
<script>
  new AlphaSenseWidget({
    target: '#generative-search',
    widgetType: 'generativeSearch',
  }).init();
</script>

Continuing Existing Conversations

new AlphaSenseWidget({
  target: '#search-continued',
  widgetType: 'generativeSearch',
  generativeSearchParams: {
    conversationId: '1234567890__987654321'
  }
}).init();

Configuration Options

Required Parameters

Parameter	Type	Description
target	string | HTMLElement	Container element selector or HTMLElement
widgetType	string	Must be 'generativeSearch'

Optional Parameters

Parameter	Type	Default	Description
generativeSearchParams.conversationId	string	undefined	The conversation ID to continue an existing conversation
generativeSearchParams.initialPrompt	string	undefined	The initial prompt to start a new conversation with
width	string	'100%'	Widget width (CSS units)
height	string	'100%'	Widget height (CSS units)
onDocumentClick	function	undefined	Callback for citation clicks (receives document ID)

Advanced Configuration

const generativeSearch = new AlphaSenseWidget({
  target: document.getElementById('my-search'), // HTMLElement instead of selector
  widgetType: 'generativeSearch',
  generativeSearchParams: {
    initialPrompt: 'What are the key trends in renewable energy investments?'
  },
  width: '800px',
  height: '600px',
  onDocumentClick: (docId) => {
    console.log('Citation clicked:', docId);
    updateDocumentViewer(docId);
  }
}).init();

ES6 Modules

import { AlphaSenseWidget } from '@alphasense/embedded-widgets';

const generativeSearch = new AlphaSenseWidget({
  target: '#generative-search',
  widgetType: 'generativeSearch',
  generativeSearchParams: {
    initialPrompt: 'What are the latest Intel results?'
  },
  width: '100%',
  height: '600px',
}).init();

Conversation Management

The Generative Search widget supports both starting new conversations and continuing existing ones:

Starting New Conversations

// Start a new conversation with an initial prompt
const newConversation = new AlphaSenseWidget({
  target: '#search-new',
  widgetType: 'generativeSearch',
  generativeSearchParams: {
    initialPrompt: 'Analyze Apple\'s recent quarterly performance'
  }
}).init();

// Start a new conversation without initial prompt (user types first message)
const emptyConversation = new AlphaSenseWidget({
  target: '#search-empty',
  widgetType: 'generativeSearch'
}).init();

Continuing Existing Conversations

// Continue an existing conversation using its ID
const existingConversation = new AlphaSenseWidget({
  target: '#search-existing',
  widgetType: 'generativeSearch',
  generativeSearchParams: {
    conversationId: '1234567890__987654321'
  }
}).init();

Important Notes

• initialPrompt is ignored when conversationId is provided, as it only works with new conversations
• Each conversation maintains its own context and message history
• Conversation IDs are automatically generated by the widget for new conversations

Integration Patterns

For complete implementation examples including:

• Citation handling with Document Viewer
• Side-by-side layouts and research interfaces
• Memory management and error handling
• Responsive design patterns

See the comprehensive Widget Integration Patterns guide.

Error Handling

Validation Errors

The Generative Search widget validates the parameters provided:

try {
  const generativeSearch = new AlphaSenseWidget({
    target: '#generative-search',
    widgetType: 'generativeSearch',
    generativeSearchParams: {
      conversationId: 'invalid-format' // Invalid conversation ID format
    }
  }).init();
} catch (error) {
  console.error('Generative Search initialization failed:', error.message);

  // Show fallback content
  document.getElementById('generative-search').innerHTML =
    '<div class="error">Unable to load search interface. Please try again.</div>';
}

Runtime Error Handling

function initializeSearch(params) {
  try {
    // Validate parameters before initializing
    if (params.conversationId && typeof params.conversationId !== 'string') {
      throw new Error('Invalid conversation ID format');
    }

    if (params.initialPrompt && typeof params.initialPrompt !== 'string') {
      throw new Error('Invalid initial prompt format');
    }

    const search = new AlphaSenseWidget({
      target: '#generative-search',
      widgetType: 'generativeSearch',
      generativeSearchParams: params
    }).init();

  } catch (error) {
    console.error('Failed to initialize Generative Search:', error.message);

    // Show error state
    document.getElementById('generative-search').innerHTML =
      `<div class="error">Search initialization failed: ${error.message}</div>`;
  }
}

Loading States

function updateSearchWidget(params) {
  document.getElementById('generative-search').innerHTML =
    '<div class="loading">Loading search interface...</div>';

  try {
    const search = new AlphaSenseWidget({
      target: '#generative-search',
      widgetType: 'generativeSearch',
      generativeSearchParams: params
    }).init();
  } catch (error) {
    // Handle error as shown above
  }
}

Important Notes

• initialPrompt is ignored when conversationId is provided, as it only works with new conversations
• Each conversation maintains its own context and message history

Best Practices

Performance

• Conversation reuse: Continue existing conversations when possible to maintain context
• Memory management: Always call destroy() on existing widget instances before creating new widget instances (in case of dynamic widget creation)
• Citation handling: Implement efficient document loading for citation clicks