refactor(api): switch public ask-ai config to Typesense conversational search

Author: tharropoulos

packages/docsearch-react/src/DocSearch.tsx

@@ -21,7 +21,7 @@ import type {
   DocumentSchema,
   SearchParams as TypesenseSearchParams,
 } from 'typesense/lib/Typesense/Documents';
-import type { MultiSearchRequestSchema } from "typesense/lib/Typesense/Types"
+import type { MultiSearchRequestSchema } from 'typesense/lib/Typesense/Types';
 
 import { DocSearchButton } from './DocSearchButton';
 import { DocSearchModal } from './DocSearchModal';
@@ -33,6 +33,7 @@ import type {
 } from './types';
 
 import type { ButtonTranslations, ModalTranslations } from '.';
+import type { TypesenseAskAiSearchParameters } from './types/AskiAi';
 
 export type { DocSearchRef } from '@docsearch/core';
 
@@ -54,85 +55,33 @@ export type DocSearchTransformClient = {
   transporter: Pick<LiteClient['transporter'], 'algoliaAgent'>;
 };
 
-// Define the specific search parameters allowed for Ask AI
-export type AskAiSearchParameters = {
-  facetFilters?: string[];
-  filters?: string;
-  attributesToRetrieve?: string[];
-  restrictSearchableAttributes?: string[];
-  distinct?: boolean | number | string;
-};
-
-export type AgentStudioSearchParameters = Record<
-  string,
-  Omit<AskAiSearchParameters, 'facetFilters'>
->;
-
 export type DocSearchAskAi = {
   /**
-   * The index name to use for the ask AI feature. Your assistant will search this index for relevant documents.
-   * If not provided, the index name will be used.
+   * Typesense conversational model id.
    */
-  indexName?: string;
+  conversationModelId: string;
   /**
-   * The API key to use for the ask AI feature. Your assistant will use this API key to search the index.
-   * If not provided, the API key will be used.
+   * Collection to query for conversational retrieval.
+   * Defaults to `typesenseCollectionName`.
    */
-  apiKey?: string;
+  collection?: string;
   /**
-   * The app ID to use for the ask AI feature. Your assistant will use this app ID to search the index.
-   * If not provided, the app ID will be used.
+   * Query field to use for conversational retrieval.
+   *
+   * @default 'embedding'
    */
-  appId?: string;
+  queryBy?: string;
   /**
-   * The assistant ID to use for the ask AI feature.
+   * Fields excluded from the conversational payload.
+   *
+   * @default 'embedding'
    */
-  assistantId: string;
+  excludeFields?: string;
   /**
-   * Enables displaying suggested questions on Ask AI's new conversation screen.
-   *
-   * @default false
+   * Additional Typesense search parameters for the conversational retrieval request.
    */
-  suggestedQuestions?: boolean;
-  // HACK: This is a hack for testing staging, remove before releasing
-  useStagingEnv?: boolean;
-} & (
-    | {
-      /**
-       * **Experimental:** Whether to use Agent Studio as the chat backend.
-       *
-       * This is an experimental feature and its API may change without notice in future releases.
-       * Use with caution in production environments.
-       *
-       * @default false
-       */
-      agentStudio?: never;
-      /**
-       * The search parameters to use for the ask AI feature.
-       *
-       * **NOTE**: If using `agentStudio = true`, the `searchParameters` object is
-       * keyed by the index name.
-       */
-      searchParameters?: AskAiSearchParameters;
-    }
-    | {
-      agentStudio: false;
-      searchParameters?: AskAiSearchParameters;
-    }
-    | {
-      agentStudio: true;
-      /**
-       * The search parameters to use for the ask AI feature.
-       * Keyed by the index name.
-       *
-       * @example
-       * {
-       *   "INDEX_NAME": { distinct: false }
-       * }
-       */
-      searchParameters?: AgentStudioSearchParameters;
-    }
-  );
+  searchParameters?: TypesenseAskAiSearchParameters;
+};
 
 export interface DocSearchIndex {
   name: string;
@@ -162,9 +111,9 @@ export interface DocSearchProps {
    */
   indices?: Array<DocSearchIndex | string>;
   /**
-   * Configuration or assistant id to enable ask ai mode. Pass a string assistant id or a full config object.
+   * Configuration to enable Typesense conversational search.
    */
-  askAi?: DocSearchAskAi | string;
+  askAi?: DocSearchAskAi;
   /**
    * Intercept Ask AI requests (e.g. Submitting a prompt or selecting a suggested question).
    *

packages/docsearch-react/src/Footer.tsx

@@ -48,13 +48,13 @@ export function Footer({ translations = {}, isAskAiActive = false }: FooterProps
     backToSearchText = 'Back to search',
     closeKeyAriaLabel = 'Escape key',
     poweredByText = 'Powered by',
-    searchByText = 'Search by',
+    searchByText,
   } = translations;
 
   return (
     <>
       <div className="DocSearch-Logo">
-        <TypesenseLogo translations={{ searchByText: searchByText || poweredByText }} />
+        <TypesenseLogo translations={{ searchByText: searchByText ?? poweredByText }} />
       </div>
       <ul className="DocSearch-Commands">
         <li>

packages/docsearch-react/src/Sidepanel.tsx

@@ -1,69 +1,29 @@
 import { DocSearch, useDocSearch } from '@docsearch/core';
 import type { DocSearchCallbacks, DocSearchRef, DocSearchTheme, SidepanelShortcuts } from '@docsearch/core';
+import type { ConfigurationOptions as TypesenseConfigurationOptions } from 'typesense/lib/Typesense/Configuration';
 import type { JSX } from 'react';
 import React from 'react';
 import { createPortal } from 'react-dom';
 
-import type { AgentStudioSearchParameters, AskAiSearchParameters } from './DocSearch';
+import type { DocSearchAskAi } from './DocSearch';
 import type { SidepanelButtonProps, SidepanelProps as SidepanelPanelProps } from './Sidepanel/index';
 import { SidepanelButton, Sidepanel } from './Sidepanel/index';
 
 export type { DocSearchRef, DocSearchCallbacks } from '@docsearch/core';
 
-export type SidepanelSearchParameters =
-  | {
-      /**
-       * **Experimental:** Whether to use Agent Studio as the chat backend.
-       *
-       * This is an experimental feature and its API may change without notice in future releases.
-       * Use with caution in production environments.
-       *
-       * @default false
-       */
-      agentStudio?: never;
-      /**
-       * The search parameters to use for the ask AI feature.
-       *
-       * **NOTE**: If using `agentStudio = true`, the `searchParameters` object is
-       * keyed by the index name.
-       */
-      searchParameters?: AskAiSearchParameters;
-    }
-  | {
-      agentStudio: false;
-      searchParameters?: AskAiSearchParameters;
-    }
-  | {
-      agentStudio: true;
-      /**
-       * The search parameters to use for the ask AI feature.
-       * Keyed by the index name.
-       *
-       * @example
-       * {
-       *   "INDEX_NAME": { distinct: false }
-       * }
-       */
-      searchParameters?: AgentStudioSearchParameters;
-    };
-
 export type DocSearchSidepanelProps = DocSearchCallbacks & {
   /**
-   * The assistant ID to use for the ask AI feature.
-   */
-  assistantId: string;
-  /**
-   * Public api key with search permissions for the index.
+   * Typesense server configuration used by sidepanel search.
    */
-  apiKey: string;
+  typesenseServerConfig: TypesenseConfigurationOptions;
   /**
-   * Algolia application id used by the search client.
+   * Typesense collection name used for keyword search.
    */
-  appId: string;
+  typesenseCollectionName: string;
   /**
-   * The index name to use for the ask AI feature. Your assistant will search this index for relevant documents.
+   * Typesense conversational search configuration.
    */
-  indexName: string;
+  askAi: DocSearchAskAi;
   /**
    * Configuration for keyboard shortcuts. Allows enabling/disabling specific shortcuts.
    *
@@ -86,10 +46,8 @@ export type DocSearchSidepanelProps = DocSearchCallbacks & {
   panel?: Omit<SidepanelPanelProps, 'keyboardShortcuts'>;
 };
 
-type SidepanelProps = DocSearchSidepanelProps & SidepanelSearchParameters;
-
 function DocSearchSidepanelComponent(
-  { keyboardShortcuts, theme, onReady, onOpen, onClose, onSidepanelOpen, onSidepanelClose, ...props }: SidepanelProps,
+  { keyboardShortcuts, theme, onReady, onOpen, onClose, onSidepanelOpen, onSidepanelClose, ...props }: DocSearchSidepanelProps,
   ref: React.ForwardedRef<DocSearchRef>,
 ): JSX.Element {
   return (

packages/docsearch-react/src/Sidepanel/setSidepanelSearchClient.ts

@@ -1,10 +1,7 @@
-import type { DocSearchTransformClient } from '..';
-import { version } from '../version';
-
-export const setSidepanelSearchClient = (client: DocSearchTransformClient): DocSearchTransformClient => {
-  if (/docsearch-sidepanel.js \(.*\)/.test(client.transporter.algoliaAgent.value) === false) {
-    client.addAlgoliaAgent('docsearch-sidepanel', version);
-  }
+import type { TypesenseDocsearchTransformClient } from '../DocSearch';
 
+export const setSidepanelSearchClient = (
+  client: TypesenseDocsearchTransformClient,
+): TypesenseDocsearchTransformClient => {
   return client;
 };

packages/docsearch-react/src/TypesenseLogo.tsx

@@ -1,6 +1,6 @@
 import React, { type JSX } from 'react';
 
-type TypesenseLogoTranslations = Partial<{
+export type TypesenseLogoTranslations = Partial<{
   searchByText: string;
 }>;