@microsoft/agents-hosting-dialogs 0.1.49

package/src/choices/findValues.ts

@@ -0,0 +1,179 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ModelResult } from './modelResult'
+import { defaultTokenizer, Token, TokenizerFunction } from './tokenizer'
+
+/**
+ * Basic search options used to control how choices are recognized in a users utterance.
+ */
+export interface FindValuesOptions {
+  allowPartialMatches?: boolean;
+  locale?: string;
+  maxTokenDistance?: number;
+  tokenizer?: TokenizerFunction;
+}
+
+export interface FoundValue {
+  value: string;
+  index: number;
+  score: number;
+}
+
+export interface SortedValue {
+  value: string;
+  index: number;
+}
+
+/**
+ * INTERNAL: Low-level function that searches for a set of values within an utterance. Higher level
+ * functions like `findChoices()` and `recognizeChoices()` are layered above this function.  In most
+ * cases its easier to just call one of the higher level functions instead but this function contains
+ * the fuzzy search algorithm that drives choice recognition.
+ *
+ * @param utterance The text or user utterance to search over.
+ * @param values List of values to search over.
+ * @param options (Optional) options used to tweak the search that's performed.
+ * @returns A list of found values.
+ */
+export function findValues (
+  utterance: string,
+  values: SortedValue[],
+  options?: FindValuesOptions
+): ModelResult<FoundValue>[] {
+  function indexOfToken (token: Token, startPos: number): number {
+    for (let i: number = startPos; i < tokens.length; i++) {
+      if (tokens[i].normalized === token.normalized) {
+        return i
+      }
+    }
+
+    return -1
+  }
+
+  function findExactMatch (utterance: string, values: SortedValue[]): ModelResult<FoundValue> | null {
+    const entry = values.find(({ value }) => value.toLowerCase() === utterance.toLowerCase())
+    if (!entry) {
+      return null
+    }
+    return {
+      text: utterance,
+      start: 0,
+      end: utterance.length - 1,
+      typeName: 'value',
+      resolution: {
+        value: entry.value,
+        index: entry.index,
+        score: 1,
+      },
+    }
+  }
+
+  const exactMatch = findExactMatch(utterance, values)
+  if (exactMatch) {
+    return [exactMatch]
+  }
+
+  function matchValue (
+    index: number,
+    value: string,
+    vTokens: Token[],
+    startPos: number
+  ): ModelResult<FoundValue> | undefined {
+    let matched = 0
+    let totalDeviation = 0
+    let start = -1
+    let end = -1
+    vTokens.forEach((token: Token) => {
+      const pos: number = indexOfToken(token, startPos)
+      if (pos >= 0) {
+        const distance: number = matched > 0 ? pos - startPos : 0
+        if (distance <= maxDistance) {
+          matched++
+          totalDeviation += distance
+          startPos = pos + 1
+
+          if (start < 0) {
+            start = pos
+          }
+          end = pos
+        }
+      }
+    })
+
+    let result: ModelResult<FoundValue> | undefined
+    if (matched > 0 && (matched === vTokens.length || opt.allowPartialMatches)) {
+      const completeness: number = matched / vTokens.length
+
+      const accuracy: number = matched / (matched + totalDeviation)
+
+      const score: number = completeness * accuracy
+
+      result = {
+        start,
+        end,
+        typeName: 'value',
+        resolution: {
+          value,
+          index,
+          score,
+        },
+      } as ModelResult<FoundValue>
+    }
+
+    return result
+  }
+
+  const list: SortedValue[] = values.sort((a: SortedValue, b: SortedValue) => b.value.length - a.value.length)
+
+  let matches: ModelResult<FoundValue>[] = []
+  const opt: FindValuesOptions = options || {}
+  const tokenizer: TokenizerFunction = opt.tokenizer || defaultTokenizer
+  const tokens: Token[] = tokenizer(utterance, opt.locale)
+  const maxDistance: number = opt.maxTokenDistance !== undefined ? opt.maxTokenDistance : 2
+  list.forEach((entry: SortedValue) => {
+    let startPos = 0
+    const vTokens: Token[] = tokenizer(entry.value.trim(), opt.locale)
+    while (startPos < tokens.length) {
+      const match = matchValue(entry.index, entry.value, vTokens, startPos)
+      if (match) {
+        startPos = match.end + 1
+        matches.push(match)
+      } else {
+        break
+      }
+    }
+  })
+
+  matches = matches.sort(
+    (a: ModelResult<FoundValue>, b: ModelResult<FoundValue>) => b.resolution.score - a.resolution.score
+  )
+
+  const results: ModelResult<FoundValue>[] = []
+  const foundIndexes: { [index: number]: boolean } = {}
+  const usedTokens: { [index: number]: boolean } = {}
+  matches.forEach((match: ModelResult<FoundValue>) => {
+    let add = !Object.prototype.hasOwnProperty.call(foundIndexes, match.resolution.index)
+    for (let i: number = match.start; i <= match.end; i++) {
+      if (usedTokens[i]) {
+        add = false
+        break
+      }
+    }
+
+    if (add) {
+      foundIndexes[match.resolution.index] = true
+      for (let i: number = match.start; i <= match.end; i++) {
+        usedTokens[i] = true
+      }
+
+      match.start = tokens[match.start].start
+      match.end = tokens[match.end].end
+      match.text = utterance.substring(match.start, match.end + 1)
+      results.push(match)
+    }
+  })
+
+  return results.sort((a: ModelResult<FoundValue>, b: ModelResult<FoundValue>) => a.start - b.start)
+}

package/src/choices/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export * from './choice'
+export * from './choiceFactory'
+export * from './findChoices'
+export * from './findValues'
+export * from './modelResult'
+export * from './recognizeChoices'
+export * from './tokenizer'

package/src/choices/modelResult.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export interface ModelResult<T extends Record<string, any> = {}> {
+  text: string;
+  start: number;
+  end: number;
+  typeName: string;
+  resolution: T;
+}

package/src/choices/recognizeChoices.ts

@@ -0,0 +1,94 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { findChoices, FindChoicesOptions, FoundChoice } from './findChoices'
+import { ModelResult } from './modelResult'
+import { Choice } from './choice'
+import { debug } from '@microsoft/agents-hosting'
+
+const logger = debug('dialogs:recognizeChoices')
+
+/**
+ * High level function for recognizing a choice in a users utterance.
+ *
+ * @param utterance The text or user utterance to search over. For an incoming 'message' activity you can simply use `context.activity.text`.
+ * @param choices List of choices to search over.
+ * @param options (Optional) options used to tweak the search that's performed.
+ * @returns A list of found choices, sorted by most relevant first.
+ */
+export function recognizeChoices (
+  utterance: string,
+  choices: (string | Choice)[],
+  options?: FindChoicesOptions
+): ModelResult<FoundChoice>[] {
+  function matchChoiceByIndex (match: ModelResult<any>): void {
+    try {
+      const index: number = parseInt(match.resolution.value, 10) - 1
+      if (index >= 0 && index < list.length) {
+        const choice: Choice = list[index]
+        matched.push({
+          start: match.start,
+          end: match.end,
+          typeName: 'choice',
+          text: match.text,
+          resolution: {
+            value: choice.value,
+            index,
+            score: 1,
+          },
+        })
+      }
+    } catch (error: any) {
+      logger.error('Error: ', error)
+      throw error
+    }
+  }
+
+  // Initialize options
+  options = Object.assign(
+    {
+      locale: 'en-us',
+      recognizeNumbers: true,
+      recognizeOrdinals: true,
+    } as FindChoicesOptions,
+    options
+  )
+
+  // Normalize choices
+  const list: Choice[] = (choices || [])
+    .map((choice) => (typeof choice === 'string' ? { value: choice } : choice))
+    .filter(
+      (choice: Choice) => choice // TODO: does this do anything?
+    )
+
+  // Try finding choices by text search first
+  // - We only want to use a single strategy for returning results to avoid issues where utterances
+  //   like the "the third one" or "the red one" or "the first division book" would miss-recognize as
+  //   a numerical index or ordinal as well.
+  let matched: ModelResult<FoundChoice>[] = findChoices(utterance, list, options)
+  if (matched.length === 0) {
+    // Next try finding by ordinal
+    if (options.recognizeOrdinals) {
+      // TODO: Review recognizeOrdinal function
+      // const ordinals: ModelResult[] = Recognizers.recognizeOrdinal(utterance, options.locale ?? '')
+      const ordinals: ModelResult[] = []
+      ordinals.forEach(matchChoiceByIndex)
+    }
+
+    // Finally try by numerical index
+    if (matched.length === 0 && options.recognizeNumbers) {
+      // TODO: Review recognizeNumber function
+      // const numbers: ModelResult[] = Recognizers.recognizeNumber(utterance, options.locale ?? '').forEach(matchChoiceByIndex)
+      const numbers: ModelResult[] = []
+      numbers.forEach(matchChoiceByIndex)
+    }
+
+    // Sort any found matches by their position within the utterance.
+    // - The results from findChoices() are already properly sorted so we just need this
+    //   for ordinal & numerical lookups.
+    matched = matched.sort((a: ModelResult<FoundChoice>, b: ModelResult<FoundChoice>) => a.start - b.start)
+  }
+
+  return matched
+}

package/src/choices/tokenizer.ts

@@ -0,0 +1,93 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export interface Token {
+  start: number;
+  end: number;
+  text: string;
+  normalized: string;
+}
+
+/**
+ * Signature for an alternate word breaker.
+ *
+ * @param TokenizerFunction.text The text to be tokenized.
+ * @param TokenizerFunction.locale (Optional) locale of the text if known.
+ */
+export type TokenizerFunction = (text: string, locale?: string) => Token[]
+
+/**
+ * Simple tokenizer that breaks on spaces and punctuation.
+ *
+ * @param text The input text.
+ * @param _locale Optional, identifies the locale of the input text.
+ * @returns A list of tokens.
+ */
+export function defaultTokenizer (text: string, _locale?: string): Token[] {
+  const tokens: Token[] = []
+  let token: Token | undefined
+
+  function appendToken (end: number): void {
+    if (token) {
+      token.end = end
+      token.normalized = token.text.toLowerCase()
+      tokens.push(token)
+      token = undefined
+    }
+  }
+
+  // Parse text
+  const length: number = text ? text.length : 0
+  let i = 0
+  while (i < length) {
+    const codePoint: number = text.codePointAt(i) || text.charCodeAt(i)
+    const chr: string = String.fromCodePoint(codePoint)
+
+    if (isBreakingChar(codePoint)) {
+      appendToken(i - 1)
+    } else if (codePoint > 0xffff) {
+      appendToken(i - 1)
+      tokens.push({
+        start: i,
+        end: i + (chr.length - 1),
+        text: chr,
+        normalized: chr,
+      })
+    } else if (!token) {
+      token = { start: i, text: chr } as Token
+    } else {
+      token.text += chr
+    }
+    i += chr.length
+  }
+  appendToken(length - 1)
+
+  return tokens
+}
+
+/**
+ * @private
+ * @param codePoint number of character
+ */
+function isBreakingChar (codePoint: number): boolean {
+  return (
+    isBetween(codePoint, 0x0000, 0x002f) ||
+        isBetween(codePoint, 0x003a, 0x0040) ||
+        isBetween(codePoint, 0x005b, 0x0060) ||
+        isBetween(codePoint, 0x007b, 0x00bf) ||
+        isBetween(codePoint, 0x02b9, 0x036f) ||
+        isBetween(codePoint, 0x2000, 0x2bff) ||
+        isBetween(codePoint, 0x2e00, 0x2e7f)
+  )
+}
+
+/**
+ * @private
+ * @param value number value
+ * @param from low range
+ * @param to high range
+ */
+function isBetween (value: number, from: number, to: number): boolean {
+  return value >= from && value <= to
+}

package/src/componentDialog.ts

@@ -0,0 +1,306 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { TurnContext } from '@microsoft/agents-hosting'
+import { Dialog } from './dialog'
+import { DialogContext } from './dialogContext'
+import { DialogContainer } from './dialogContainer'
+import { DialogTurnResult } from './dialogTurnResult'
+import { DialogReason } from './dialogReason'
+import { DialogInstance } from './dialogInstance'
+import { DialogTurnStatus } from './dialogTurnStatus'
+
+const PERSISTED_DIALOG_STATE = 'dialogs'
+
+/**
+ * Base class for a dialog that contains other child dialogs.
+ *
+ * @remarks
+ * Component dialogs let you break your agent's logic up into components that can themselves be added
+ * as a dialog to another `ComponentDialog` or `DialogSet`. Components can also be exported as part
+ * of a node package and used within other agents.
+ *
+ * @param O (Optional) options that can be passed into the `DialogContext.beginDialog()` method.
+ */
+export class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
+  /**
+     * ID of the child dialog that should be started anytime the component is started.
+     *
+     * @remarks
+     * This defaults to the ID of the first child dialog added using [addDialog()](#adddialog).
+     */
+  protected initialDialogId: string
+
+  /**
+     * Called when the dialog is started and pushed onto the parent's dialog stack.
+     * By default, this calls the
+     * Dialog.BeginDialogAsync(DialogContext, object, CancellationToken) method
+     * of the component dialog's initial dialog, as defined by InitialDialogId.
+     * Override this method in a derived class to implement interrupt logic.
+     *
+     * @param outerDialogContext The parent DialogContext for the current turn of conversation.
+     * @param options Optional, initial information to pass to the dialog.
+     * @returns A Promise representing the asynchronous operation.
+     * @remarks
+     * If the task is successful, the result indicates whether the dialog is still
+     * active after the turn has been processed by the dialog.
+     */
+  async beginDialog (outerDialogContext: DialogContext, options?: O): Promise<DialogTurnResult> {
+    await this.checkForVersionChange(outerDialogContext)
+
+    // Start the inner dialog.
+    const innerDC: DialogContext = this.createChildContext(outerDialogContext)
+    const turnResult: DialogTurnResult<any> = await this.onBeginDialog(innerDC, options)
+
+    // Check for end of inner dialog
+    if (turnResult.status !== DialogTurnStatus.waiting) {
+      if (turnResult.status === DialogTurnStatus.cancelled) {
+        await this.endComponent(outerDialogContext, turnResult.result)
+        const cancelledTurnResult: DialogTurnResult = {
+          status: DialogTurnStatus.cancelled,
+          result: turnResult.result,
+        }
+        return cancelledTurnResult
+      }
+      // Return result to calling dialog
+      return await this.endComponent(outerDialogContext, turnResult.result)
+    }
+    // Just signal end of turn
+    return Dialog.EndOfTurn
+  }
+
+  /**
+     * Called when the dialog is _continued_, where it is the active dialog and the
+     * user replies with a new Activity.
+     * If this method is *not* overridden, the dialog automatically ends when the user replies.
+     *
+     * @param outerDialogContext The parent DialogContext for the current turn of conversation.
+     * @returns A Promise representing the asynchronous operation.
+     * @remarks
+     * If the task is successful, the result indicates whether the dialog is still
+     * active after the turn has been processed by the dialog. The result may also contain a
+     * return value.
+     */
+  async continueDialog (outerDialogContext: DialogContext): Promise<DialogTurnResult> {
+    await this.checkForVersionChange(outerDialogContext)
+
+    // Continue execution of inner dialog.
+    const innerDC: DialogContext = this.createChildContext(outerDialogContext)
+    const turnResult: DialogTurnResult<any> = await this.onContinueDialog(innerDC)
+
+    // Check for end of inner dialog
+    if (turnResult.status !== DialogTurnStatus.waiting) {
+      // Return result to calling dialog
+      return await this.endComponent(outerDialogContext, turnResult.result)
+    }
+
+    // Just signal end of turn
+    return Dialog.EndOfTurn
+  }
+
+  /**
+     * Called when a child dialog on the parent's dialog stack completed this turn, returning
+     * control to this dialog component.
+     *
+     * @param outerDialogContext The DialogContext for the current turn of conversation.
+     * @param _reason Reason why the dialog resumed.
+     * @param _result Optional, value returned from the dialog that was called. The type
+     * of the value returned is dependent on the child dialog.
+     * @returns A Promise representing the asynchronous operation.
+     * @remarks
+     * If the task is successful, the result indicates whether this dialog is still
+     * active after this dialog turn has been processed.
+     * Generally, the child dialog was started with a call to
+     * beginDialog(DialogContext, object) in the parent's
+     * context. However, if the DialogContext.replaceDialog(string, object) method
+     * is called, the logical child dialog may be different than the original.
+     * If this method is *not* overridden, the dialog automatically calls its
+     * RepromptDialog(ITurnContext, DialogInstance) when the user replies.
+     */
+  async resumeDialog (outerDialogContext: DialogContext, _reason: DialogReason, _result?: any): Promise<DialogTurnResult> {
+    await this.checkForVersionChange(outerDialogContext)
+
+    // Containers are typically leaf nodes on the stack but the dev is free to push other dialogs
+    // on top of the stack which will result in the container receiving an unexpected call to
+    // resumeDialog() when the pushed on dialog ends.
+    // To avoid the container prematurely ending we need to implement this method and simply
+    // ask our inner dialog stack to re-prompt.
+    await this.repromptDialog(outerDialogContext.context, outerDialogContext.activeDialog)
+
+    return Dialog.EndOfTurn
+  }
+
+  /**
+     * Called when the dialog should re-prompt the user for input.
+     *
+     * @param context The TurnContext object for this turn.
+     * @param instance State information for this dialog.
+     * @returns A Promise representing the asynchronous operation.
+     */
+  async repromptDialog (context: TurnContext, instance: DialogInstance): Promise<void> {
+    // Forward to inner dialogs
+    const innerDC: DialogContext = this.createInnerDC(context, instance)
+    await innerDC.repromptDialog()
+
+    // Notify component.
+    await this.onRepromptDialog(context, instance)
+  }
+
+  /**
+     * Called when the Dialog is ending.
+     *
+     * @param context The TurnContext object for this turn.
+     * @param instance State information associated with the instance of this component Dialog on its parent's dialog stack.
+     * @param reason Reason why the Dialog ended.
+     * @returns A Promise representing the asynchronous operation.
+     * @remarks When this method is called from the parent dialog's context, the component Dialog
+     * cancels all of the dialogs on its inner dialog stack before ending.
+     */
+  async endDialog (context: TurnContext, instance: DialogInstance, reason: DialogReason): Promise<void> {
+    // Forward cancel to inner dialogs
+    if (reason === DialogReason.cancelCalled) {
+      const innerDC: DialogContext = this.createInnerDC(context, instance)
+      await innerDC.cancelAllDialogs()
+    }
+
+    // Notify component
+    await this.onEndDialog(context, instance, reason)
+  }
+
+  /**
+     * Adds a child Dialog or prompt to the components internal DialogSet.
+     *
+     * @param dialog The child Dialog or prompt to add.
+     * @returns The ComponentDialog after the operation is complete.
+     * @remarks
+     * The Dialog.id of the first child added to the component will be assigned to the initialDialogId property.
+     */
+  addDialog (dialog: Dialog): this {
+    this.dialogs.add(dialog)
+    if (this.initialDialogId === undefined) {
+      this.initialDialogId = dialog.id
+    }
+
+    return this
+  }
+
+  /**
+     * Creates the inner dialog context
+     *
+     * @param outerDialogContext the outer dialog context
+     * @returns The created Dialog Context.
+     */
+  createChildContext (outerDialogContext: DialogContext): DialogContext {
+    return this.createInnerDC(outerDialogContext, outerDialogContext.activeDialog)
+  }
+
+  /**
+     * Called anytime an instance of the component has been started.
+     *
+     * @remarks
+     * SHOULD be overridden by components that wish to perform custom interruption logic. The
+     * default implementation calls `innerDC.beginDialog()` with the dialog assigned to
+     * initialdialogid.
+     * @param innerDialogContext Dialog context for the components internal `DialogSet`.
+     * @param options (Optional) options that were passed to the component by its parent.
+     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
+     */
+  protected onBeginDialog (innerDialogContext: DialogContext, options?: O): Promise<DialogTurnResult> {
+    return innerDialogContext.beginDialog(this.initialDialogId, options)
+  }
+
+  /**
+     * Called anytime a multi-turn component receives additional activities.
+     *
+     * @remarks
+     * SHOULD be overridden by components that wish to perform custom interruption logic. The
+     * default implementation calls `innerDC.continueDialog()`.
+     * @param innerDC Dialog context for the components internal `DialogSet`.
+     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
+     */
+  protected onContinueDialog (innerDC: DialogContext): Promise<DialogTurnResult> {
+    return innerDC.continueDialog()
+  }
+
+  /**
+     * Called when the component is ending.
+     *
+     * @remarks
+     * If the `reason` code is equal to `DialogReason.cancelCalled`, then any active child dialogs
+     * will be cancelled before this method is called.
+     * @param _context Context for the current turn of conversation.
+     * @param _instance The components instance data within its parents dialog stack.
+     * @param _reason The reason the component is ending.
+     * @returns A promise representing the asynchronous operation.
+     */
+  protected onEndDialog (_context: TurnContext, _instance: DialogInstance, _reason: DialogReason): Promise<void> {
+    return Promise.resolve()
+  }
+
+  /**
+     * Called when the component has been requested to re-prompt the user for input.
+     *
+     * @remarks
+     * The active child dialog will have already been asked to reprompt before this method is called.
+     * @param _context Context for the current turn of conversation.
+     * @param _instance The instance of the current dialog.
+     * @returns A promise representing the asynchronous operation.
+     */
+  protected onRepromptDialog (_context: TurnContext, _instance: DialogInstance): Promise<void> {
+    return Promise.resolve()
+  }
+
+  /**
+     * Called when the components last active child dialog ends and the component is ending.
+     *
+     * @remarks
+     * SHOULD be overridden by components that wish to perform custom logic before the component
+     * ends.  The default implementation calls `outerDC.endDialog()` with the `result` returned
+     * from the last active child dialog.
+     * @param outerDC Dialog context for the parents `DialogSet`.
+     * @param result Result returned by the last active child dialog. Can be a value of `undefined`.
+     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
+     */
+  protected endComponent (outerDC: DialogContext, result: any): Promise<DialogTurnResult> {
+    return outerDC.endDialog(result)
+  }
+
+  /**
+     * @private
+     * @param context DialogContext for the current turn of conversation with the user.
+     * @param instance DialogInstance which contains the current state information for this dialog.
+     * @returns A new DialogContext instance.
+     * @remarks
+     * You should only call this if you don't have a dialogContext to work with (such as OnResume())
+     */
+  private createInnerDC (context: DialogContext, instance: DialogInstance): DialogContext
+  /**
+     * @private
+     * @param context TurnContext for the current turn of conversation with the user.
+     * @param instance DialogInstance which contains the current state information for this dialog.
+     * @returns A new DialogContext instance.
+     * @remarks
+     * You should only call this if you don't have a dc to work with (such as OnResume())
+     */
+  private createInnerDC (context: TurnContext, instance: DialogInstance): DialogContext
+  /**
+     * @private
+     * @param context TurnContext or DialogContext for the current turn of conversation with the user.
+     * @param instance DialogInstance which contains the current state information for this dialog.
+     * @returns A new DialogContext instance.
+     * @remarks
+     * You should only call this if you don't have a dc to work with (such as OnResume())
+     */
+  private createInnerDC (context: TurnContext | DialogContext, instance: DialogInstance): DialogContext {
+    if (!instance) {
+      const dialogInstance = { state: {} }
+      instance = dialogInstance as DialogInstance
+    }
+
+    const dialogState = instance.state[PERSISTED_DIALOG_STATE] || { dialogStack: [] }
+    instance.state[PERSISTED_DIALOG_STATE] = dialogState
+
+    return new DialogContext(this.dialogs, context as TurnContext, dialogState)
+  }
+}