@stack-spot/ai-chat-widget 0.10.0 → 1.0.0-dev.1768314799914

package/src/right-panel/hooks.tsx

@@ -1,6 +1,7 @@
 import { useContext, useMemo } from 'react'
 import { DefaultPanel } from './DefaultPanel'
 import { RightPanelContext } from './RightPanelProvider'
+import { panelAnimationTime } from './constants'
 
 interface RightPanelOptions {
   title: React.ReactNode,
@@ -8,11 +9,17 @@ interface RightPanelOptions {
   onClose?: () => void,
 }
 
+/**
+ * @returns teh current content of the right panel
+ */
 export function useRightPanelContent() {
   const { content } = useContext(RightPanelContext)
   return content
 }
 
+/**
+ * Opens, closes or checks the visibility of the right panel.
+ */
 export function useRightPanel() {
   const ctx = useContext(RightPanelContext)
   const { panel, chatWindow, setContent } = ctx
@@ -35,7 +42,7 @@ export function useRightPanel() {
       ctx.onCloseNext.current?.()
       setTimeout(() => {
         setContent(null)
-      }, 300)
+      }, panelAnimationTime)
     }
 
     function isOpen() {

package/src/state/ChatEntry.ts

@@ -1,13 +1,26 @@
+import { ChatStep, HypothesisPMAgent, OpportunitiesPMAgent, PrfaqPMAgent } from '@stack-spot/portal-network'
+import { ColorPaletteName, ColorSchemeName } from '@stack-spot/portal-theme'
 import { pull } from 'lodash'
-import { LabeledWithImage } from './types'
+import { LabeledAgent } from './types'
+
+export interface ActionDataClick {
+  name?: string,
+  value?: string[],
+}
 
 export interface SerializableAction {
+  /**
+   * The text for the button or anchor.
+   */
   title: string,
+  /**
+   * Links open new tabs with urls, while commands send text commands in the chat as if they were written by the user.
+   */
   type: 'link' | 'command',
   /**
-   * The URL if the action is a link or a chat command otherwise (/command).
+   * The URL if the action is a link. The content of the user message otherwise.
    */
-  exec: string,
+  exec?: string,
 }
 
 export interface ChatAction extends SerializableAction {
@@ -15,6 +28,26 @@ export interface ChatAction extends SerializableAction {
    * @default primary
    */
   appearance?: 'primary' | 'secondary',
+  /**
+   * @default inverse
+   */
+  colorScheme?: ColorSchemeName,
+  /**
+   * @default false
+   */
+  hideWhenNotLast?: boolean,
+  /**
+   * @default false
+   */
+  disabled?: boolean,
+  /**
+   * @default button
+   */
+  buttonType?: 'submit' | 'button',
+  /**
+  * @default lg
+  */
+  size?: 'lg' | 'md' | 'sm',
 }
 
 export interface KnowledgeSource {
@@ -24,55 +57,192 @@ export interface KnowledgeSource {
   documentId: string,
 }
 
+export interface ChatTool {
+  id: string,
+  image?: string,
+  name: string,
+  description: string,
+}
+
+export interface UploadedFile {
+  id: string,
+  name: string,
+  image?: string,
+}
+
 export interface TextChatEntry {
-  type: 'text' | 'md',
+  /**
+   * "text" for simple unformatted paragraphs. "md" for markdown. 
+   * "input-text" for text inputs, 'input-radio' and "input-checkbox" for radio and checkbox inputs,
+   * "input-phone" for phone formatted inputs and "button-list" for a list of buttons in which only one is selected
+   */
+  type: 'text' | 'md' | 'input-text' | 'input-radio' | 'button-list' | 'input-checkbox' | 'input-phone',
+  /**
+   * If the message was typed by the AI agent (bot), the user or the system (not currently in use).
+   */
   agentType: 'bot' | 'user' | 'system',
-  // image?: string,
+  /**
+   * A set of buttons to go after the message.
+   */
   actions?: ChatAction[],
-  subtitle?: string,
+  /**
+   * The content of the message.
+   */
   content: string,
+  /**
+   * The actual data to send as a message. This is the "content" if not provided.
+   * 
+   * Useful for displaying a text in the chat, via "content", but sending something different to the backend.
+   * 
+   * Serialization: if none of your interceptors return false, this will be converted to a JSON in the last interceptor (sendMessage).
+   * 
+   * Attention: this is ignored by quick commands, which will always use "content".
+   */
+  data?: any,
+  /**
+   * A content that is not shown to the user, it is used only to share data.
+   * 
+   * This is used solely by the onboarding feature (checkboxes and radio button), implemented in the AI Portal. Maybe it shouldn't be
+   * implemented here. This needs a review (fixme).
+   * 
+   * This has been implemented because the message rendered is different than the message we wanted to send to the backend.
+   * 
+   * @deprecated prefer "data" instead.
+   */
+  hiddenContent?: string[],
+  /**
+   * The knowledge sources used to create the message.
+   */
   knowledgeSources?: KnowledgeSource[],
+  /**
+   * The date and time of the message. ISO string.
+   */
   updated?: string,
-  agent?: LabeledWithImage,
+  /**
+   * The agent who wrote the message. Undefined for the agentType is "user".
+   */
+  agent?: LabeledAgent,
+  /**
+   * The unique identifier of the message.
+   */
   messageId?: string,
+  /**
+   * If this is set, only an error message is rendered.
+   */
   error?: string,
-  // customInput?: CustomInputResponse,
+  /**
+   * A series of badges to display before the content.
+   */
+  badges?: { color?: ColorPaletteName, label: string }[],
+  /**
+   * Whether or not to show this chat entry as a card.
+   */
+  card?: boolean,
+  /**
+   * This entry may contain steps. If so, specify them in this array.
+   */
+  steps?: ChatStep[],
+  /**
+   * If any tool was used to generate the response, its id is returned in this list.
+   */
+  tools?: string[],
+  /**
+  * If opportunities exists in pm agent, its send in this list.
+  */
+  opportunities?: OpportunitiesPMAgent[],
+  /**
+  * If hypothesis exists in pm agent, its send in this list.
+  */
+  hypothesis?: HypothesisPMAgent[],
+  /**
+  * If prfaq exists in pm agent, its send in this object.
+  */
+  prfaq?: PrfaqPMAgent,
+  /*
+   * Options for radio, checkbox or button type.
+   */
+  options?: { color?: ColorSchemeName, label: string, value?: string, hasInput?: boolean }[],
+  /**
+   * Name to be used in input type fields.
+   */
+  name?: string,
+  /**
+   * Whether or not a input field is required.
+   */
+  required?: boolean,
+  /**
+   * The validations of input fields.
+   */
+  validations?: {
+    minLength?: number,
+    maxLength?: number,
+    pattern?: string,
+  },
+  /**
+   * Valid for input types.
+   */
+  initialValue?: string[],
+  /**
+   * If this chat entry contains any uploaded file, these are the files being uploaded along the message.
+   */
+  upload?: UploadedFile[],
+  /**
+   * True if the entry is done streaming, false otherwise. Undefined may be used when streaming info is not available.
+   */
+  done?: boolean,
+  /**
+   * True if, at some point, this entry had a planning stage (related to tools).
+   */
+  hasPlanning?: boolean,
 }
 
 type ChatEntryListener = (value: TextChatEntry) => void
 
+// this id is unique for each message and used for rendering. The `messageId`, which comes from the backend, is not always available and, 
+// therefore, can't be used for this purpose.
 let nextId = 0
 
+/**
+ * A message (entry) in the chat.
+ */
 export class ChatEntry {
   readonly id: number
   private value: TextChatEntry
-  private streamFinished: boolean
   private listeners: ChatEntryListener[] = []
-  abort: () => void
 
   /**
    * @param value the value of the entry.
-   * @param isStreamed whether or not this entry is streamed. Defaults to false.
-   * @param abort an abort function to cancel the transmission of this chat entry. Specially useful for canceling streamings.
    */
-  constructor(value: TextChatEntry, isStreamed = false, abort = () => {}) {
+  constructor(value: TextChatEntry) {
     this.id = nextId++
     this.value = value
-    this.streamFinished = !isStreamed
-    this.abort = abort
   }
 
-  static createUserEntry(content: string, isMd = false) {
+  /**
+   * Utility function to create a user entry.
+   * @param content the message's content.
+   * @param isMd whether or not this should be rendered as markdown.
+   * @param hiddenContent the message's content.
+   * @returns a new ChatEntry.
+   */
+  static createUserEntry(content: string, isMd = false, fieldName?: string, hiddenContent?: string[], data?: any) {
     return new ChatEntry({
       agentType: 'user',
       type: isMd ? 'md' : 'text',
       content,
+      name: fieldName,
+      hiddenContent,
+      data,
       updated: new Date().toISOString(),
     })
   }
 
-  static createStreamedBotEntry(abort: () => void) {
-    return new ChatEntry({ agentType: 'bot', type: 'md', content: '' }, true, abort)
+  /**
+   * Utility function to create a streamed entry from the AI agent.
+   * @returns a new ChatEntry.
+   */
+  static createStreamedBotEntry() {
+    return new ChatEntry({ agentType: 'bot', type: 'md', content: '', done: false })
   }
 
   setValue(value: TextChatEntry) {
@@ -84,16 +254,13 @@ export class ChatEntry {
     return this.value
   }
 
-  finish() {
-    this.streamFinished = true
-  }
-
-  hasFinished() {
-    return this.streamFinished
-  }
-
+  /**
+   * Watches the value of this ChatEntry.
+   * @param listener a function to call whenever the value changes.
+   * @returns a function that removes the listener.
+   */
   onChange(listener: ChatEntryListener) {
-    if (!this.streamFinished) this.listeners.push(listener)
+    this.listeners.push(listener)
     return () => {
       pull(this.listeners, listener)
     }

package/src/state/ChatState.ts

@@ -1,15 +1,45 @@
 import { dropRight, last, pull } from 'lodash'
+import { ulid } from 'ulid'
+import { AbortedError } from '../AbortedError'
+import { ChatFeatures, getFeaturesWithDefaults } from '../features'
+import { UploadManager } from '../utils/upload/UploadManager'
 import { ChatEntry } from './ChatEntry'
+import { acceptedFileTypes, maxFileSize, maxUploadItems } from './constants'
 import { ObservableState } from './ObservableState'
-import { Labeled, LabeledWithImage } from './types'
+import { Labeled, LabeledAgent } from './types'
 
-export interface ChatProperties {
+export interface ChatPropertiesWithOptionalFeatures {
+  /**
+   * The name of the chat.
+   */
   label: string,
-  agent?: LabeledWithImage & { builtIn: boolean },
+  /**
+   * The current AI agent.
+   */
+  agent?: LabeledAgent,
+  /**
+   * The current workspace.
+   */
   workspace?: Labeled,
+  /**
+   * The current stack.
+   */
   stack?: Labeled,
+  /**
+   * The current knowledge sources.
+   */
   knowledgeSources?: Labeled[],
+  /**
+   * Whether or not the chat is in a loading state.
+   */
   isLoading?: boolean,
+  /**
+   * Whether or not the chat is planning.
+   */
+  isPlaning?: boolean,
+  /**
+   * The value of the next message. This is the value of the text typed in the textarea below the chat.
+   */
   nextMessage?: string,
   /**
    * The current code in the editor.
@@ -20,41 +50,102 @@ export interface ChatProperties {
    */
   codeLanguage?: string,
   /**
-   * The current selection in the editor
+   * The current selection in the editor.
    */
   codeSelection?: string,
+  /**
+   * The features enabled for this chat.
+   * 
+   * If a feature is marked as false, it's disabled, otherwise it's enabled.
+   */
+  features?: Partial<ChatFeatures>,
+  /**
+   * The current LLM (Large Language Model) being used for this chat.
+   */
+  selected_model_id?: string,
+}
+
+export interface ChatProperties extends ChatPropertiesWithOptionalFeatures {
+  /**
+   * The features enabled for this chat.
+   */
+  features: ChatFeatures,
 }
 
 type ChatMessagesListener = (chat: ChatEntry[]) => void
 
-export type MessageInterceptor = (entry: ChatEntry, chat: ChatState) => boolean | undefined | void | Promise<boolean | undefined | void>
+export type MessageInterceptor = (
+  entry: ChatEntry, chat: ChatState, signal: AbortSignal,
+) => boolean | undefined | void | Promise<boolean | undefined | void>
 
 interface Options {
+  /**
+   * The unique identifier for this chat (conversationId).
+   */
   id: string,
-  initial: ChatProperties,
+  /**
+   * The initial value for the state of this chat.
+   */
+  initial: ChatPropertiesWithOptionalFeatures,
+  /**
+   * The interceptors to use for the messages pushed to this chat.
+   * 
+   * The interceptors are run whenever a new message (chat entry) is added to the chat. They're always run in the order of the array and if
+   * any returns a promise, the promise is awaited before running the next.
+   * 
+   * If an interceptor returns false or resolves to false (if a promise), the execution is interrupted, i.e. the next interceptors are not
+   * run.
+   * 
+   * An interceptor receives three parameters:
+   * 1. the chat entry added;
+   * 2. the chat state;
+   * 3. an AbortSignal that can be aborted by calling `abort()` on the ChatState. Once the signal is aborted, the interceptor must abort all
+   * of its operations.
+   * 
+   * Attention: when multiple messages are added at once, only the last goes through the interceptors. Furthermore, messages created by the
+   * constructor don't go through the interceptors, only messages added via `pushMessage` do.
+   */
   interceptors?: MessageInterceptor[],
+  /**
+   * The content of this chat, i.e. its messages.
+   */
   entries?: ChatEntry[],
+  /**
+   * Whether or not the label for this chat is real (persisted in the backend) or just a mock.
+   * 
+   * This should be true if the label is just a mock.
+   */
+  untitled?: boolean,
 }
 
+/**
+ * A chat. Each chat tab is a different ChatState.
+ */
 export class ChatState extends ObservableState<ChatProperties> {
   readonly id: string
   private entries: ChatEntry[]
   private messagesListeners: ChatMessagesListener[] = []
   private readonly interceptors: MessageInterceptor[]
-
   /**
-   * @param id the id of the chat.
-   * @param initial the initial state.
-   * @param interceptors a list of interceptors to run whenever a new message (entry) is added to the chat. If an interception function
-   * returns false, the next interceptors are not run. Attention: when multiple messages are added at once, only the last goes through the
-   * interceptors. Furthermore, messages created by the constructor don't go through the interceptors, only messages added via `pushMessage`
-   * do.
+   * A memory space (map) to be used by interceptors.
+   */
+  interceptorMemory = new Map<string, any>()
+  /**
+   * Abort signals currently active.
    */
-  constructor({ id, initial, entries = [], interceptors = [] }: Options) {
-    super(initial)
+  private abortions: AbortController[] = []
+  /**
+   * Used to manage uploads for this Chat.
+   */
+  readonly uploadManager = new UploadManager({ maxSize: maxFileSize, accept: acceptedFileTypes, maxItems: maxUploadItems })
+  untitled: boolean
+
+  constructor({ id, initial, entries = [], interceptors = [], untitled = false }: Options) {
+    super({ ...initial, features: getFeaturesWithDefaults(initial.features) })
     this.id = id
     this.interceptors = interceptors
     this.entries = entries
+    this.untitled = untitled
   }
 
   private runMessagesListeners() {
@@ -62,12 +153,24 @@ export class ChatState extends ObservableState<ChatProperties> {
   }
 
   private async runInterceptors(entry: ChatEntry) {
+    const abort = new AbortController()
+    this.abortions.push(abort)
     for (const interceptor of this.interceptors) {
-      const result = await interceptor(entry, this)
-      if (result === false) break
+      try {
+        const result = await interceptor(entry, this, abort.signal)
+        if (result === false) break
+      } catch (error) {
+        pull(this.abortions, abort)
+        throw error
+      }
     }
+    pull(this.abortions, abort)
   }
 
+  /**
+   * Adds one or more messages to the chat. Messages are appended to the end of the chat.
+   * @param entries the messages to add.
+   */
   pushMessage(...entries: ChatEntry[]) {
     if (!entries.length) return
     this.entries = [...this.entries, ...entries]
@@ -75,19 +178,71 @@ export class ChatState extends ObservableState<ChatProperties> {
     this.runInterceptors(last(entries)!)
   }
 
+  /**
+   * Removes one or more messages from the end of the chat.
+   * @param quantity the number of messages to remove. Defaults to 1.
+   */
   popMessage(quantity = 1) {
     this.entries = dropRight(this.entries, quantity)
     this.runMessagesListeners()
   }
 
+  /**
+   * @returns the current list of messages.
+   */
   getMessages() {
     return this.entries
   }
 
+  /**
+   * Watches this chat for changes in the list of messages.
+   * @param listener the function to call whenever the list of messages changes.
+   * @returns a function that removes the listener.
+   */
   onChangeMessages(listener: ChatMessagesListener) {
     this.messagesListeners.push(listener)
     return () => {
       pull(this.messagesListeners, listener)
     }
   }
+
+  /**
+   * Aborts all currently running chat interceptors.
+   */
+  abort() {
+    this.abortions.forEach(a => a.abort(new AbortedError()))
+    this.abortions = []
+  }
+
+  /**
+   * Creates a chat that has the same state value and interceptors as this one.
+   * 
+   * All abortions from this chat will be transferred to the new chat. The abortions of this chat will be cleared.
+   */
+  transferToNewChat(label: string) {
+    const newChat = new ChatState({
+      id: ulid(),
+      initial: { ...this.state, label },
+      interceptors: this.interceptors,
+    })
+    newChat.abortions = this.abortions
+    this.abortions = []
+    return newChat
+  }
+
+  /**
+   * Returns a promise that resolves when the chat is no longer loading (isLoading state).
+   * 
+   * If this is called when the chat is not loading, a resolved promise is returned.
+   */
+  whenLoadingEnds(): Promise<void> {
+    return this.get('isLoading') ? new Promise((resolve) => {
+      const removeListener = this.onChange('isLoading', (value) => {
+        if (!value) {
+          resolve()
+          removeListener()
+        }
+      })
+    }) : Promise.resolve()
+  }
 }