@microsoft/agents-hosting 0.5.1-g2e246ff274 → 0.5.4-ga4d0401645

package/src/app/streaming/clientCitation.ts

@@ -0,0 +1,102 @@
+/**
+ * @module teams-ai
+ */
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { SensitivityUsageInfo } from './sensitivityUsageInfo'
+
+export type ClientCitationIconName =
+    | 'Microsoft Word'
+    | 'Microsoft Excel'
+    | 'Microsoft PowerPoint'
+    | 'Microsoft OneNote'
+    | 'Microsoft SharePoint'
+    | 'Microsoft Visio'
+    | 'Microsoft Loop'
+    | 'Microsoft Whiteboard'
+    | 'Adobe Illustrator'
+    | 'Adobe Photoshop'
+    | 'Adobe InDesign'
+    | 'Adobe Flash'
+    | 'Sketch'
+    | 'Source Code'
+    | 'Image'
+    | 'GIF'
+    | 'Video'
+    | 'Sound'
+    | 'ZIP'
+    | 'Text'
+    | 'PDF'
+
+/**
+ * Represents a Teams client citation to be included in a message. See Bot messages with AI-generated content for more details.
+ * https://learn.microsoft.com/en-us/microsoftteams/platform/bots/how-to/bot-messages-ai-generated-content?tabs=before%2Cbotmessage
+ */
+export interface ClientCitation {
+  /**
+     * Required; must be "Claim"
+     */
+  '@type': 'Claim';
+
+  /**
+     * Required. Number and position of the citation.
+     */
+  position: number;
+  appearance: {
+    /**
+         * Required; Must be 'DigitalDocument'
+         */
+    '@type': 'DigitalDocument';
+
+    /**
+         * Name of the document. (max length 80)
+         */
+    name: string;
+
+    /**
+         * Stringified adaptive card with additional information about the citation.
+         * It is rendered within the modal.
+         */
+    text?: string;
+
+    /**
+         * URL of the document. This will make the name of the citation clickable and direct the user to the specified URL.
+         */
+    url?: string;
+
+    /**
+         * Extract of the referenced content. (max length 160)
+         */
+    abstract: string;
+
+    /**
+         * Encoding format of the `citation.appearance.text` field.
+         */
+    encodingFormat?: 'application/vnd.microsoft.card.adaptive';
+
+    /**
+         * Information about the citation’s icon.
+         */
+    image?: {
+      '@type': 'ImageObject';
+
+      /**
+             * The image/icon name
+             */
+      name: ClientCitationIconName;
+    };
+
+    /**
+         * Optional; set by developer. (max length 3) (max keyword length 28)
+         */
+    keywords?: string[];
+
+    /**
+         * Optional sensitivity content information.
+         */
+    usageInfo?: SensitivityUsageInfo;
+  };
+}

package/src/app/streaming/message.ts

@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ActionCall } from './actionCall'
+
+/**
+ * A message object sent to or received from an LLM.
+ * @param TContent Optional. Type of the message content. Defaults to `string`
+ */
+export interface Message<TContent = string> {
+  /**
+     * The messages role. Typically 'system', 'user', 'assistant', 'tool', 'function'.
+     */
+  role: string;
+
+  /**
+     * Text of the message.
+     */
+  content: TContent | undefined;
+
+  /**
+     * Optional. A named function to call.
+     */
+  function_call?: FunctionCall;
+
+  /**
+     * The context used for the message.
+     */
+  context?: MessageContext;
+
+  /**
+     * Optional. Name of the function that was called.
+     */
+  name?: string;
+
+  /**
+     * Optional. The action or tool to be called by the model when using 'tools' augmentation. In OpenAI, this is the tool_calls property returned from the model.
+     */
+  action_calls?: ActionCall[];
+
+  /**
+     * Optional. The id of the action called.
+     */
+  action_call_id?: string | undefined;
+}
+
+/**
+ * A named function to call.
+ */
+export interface FunctionCall {
+  /**
+     * Name of the function to call.
+     */
+  name?: string;
+
+  /**
+     * Optional. Arguments to pass to the function. Must be deserialized.
+     */
+  arguments?: string;
+}
+
+export type MessageContentParts = TextContentPart | ImageContentPart
+
+export interface TextContentPart {
+  /**
+     * Type of the message content. Should always be 'text'.
+     */
+  type: 'text';
+
+  /**
+     * The text of the message.
+     */
+  text: string;
+}
+
+export interface ImageContentPart {
+  /**
+     * Type of the message content. Should always be 'image_url'.
+     */
+  type: 'image_url';
+
+  /**
+     * The URL of the image.
+     */
+  image_url: string | { url: string };
+}
+
+/**
+ * Citations returned by the model.
+ */
+export interface Citation {
+  /**
+     * The content of the citation.
+     */
+  content: string;
+
+  /**
+     * The title of the citation.
+     */
+  title: string | null;
+
+  /**
+     * The URL of the citation.
+     */
+  url: string | null;
+
+  /**
+     * The filepath of the document.
+     */
+  filepath: string | null;
+}
+
+export interface MessageContext {
+  /**
+     * Citations used in the message.
+     */
+  citations: Citation[];
+
+  /**
+     * The intent of the message (what the user wrote).
+     */
+  intent: string;
+}

package/src/app/streaming/sensitivityUsageInfo.ts

@@ -0,0 +1,48 @@
+/**
+ * Sensitivity usage info for content sent to the user. This is used to provide information about the content to the user. See ClientCitation for more information.
+ */
+export interface SensitivityUsageInfo {
+  /**
+     * Must be "https://schema.org/Message"
+     */
+  type: 'https://schema.org/Message';
+
+  /**
+     * Required; Set to CreativeWork;
+     */
+  '@type': 'CreativeWork';
+
+  /**
+     * Sensitivity description of the content
+     */
+  description?: string;
+
+  /**
+     * Sensitivity title of the content
+     */
+  name: string;
+
+  /**
+     * Optional; ignored in Teams.
+     */
+  position?: number;
+
+  pattern?: {
+    /**
+         * Set to DefinedTerm
+         */
+    '@type': 'DefinedTerm';
+
+    inDefinedTermSet: string;
+
+    /**
+         * Color
+         */
+    name: string;
+
+    /**
+         * e.g. #454545
+         */
+    termCode: string;
+  };
+}

package/src/app/streaming/streamingResponse.ts

@@ -0,0 +1,406 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Activity, Attachment, Entity } from '@microsoft/agents-activity'
+import { TurnContext } from '../../turnContext'
+import { ClientCitation } from './clientCitation'
+import { SensitivityUsageInfo } from './sensitivityUsageInfo'
+import { Citation } from './message'
+import { Utilities } from './utilities'
+
+/**
+ * A helper class for streaming responses to the client.
+ * @remarks
+ * This class is used to send a series of updates to the client in a single response. The expected
+ * sequence of calls is:
+ *
+ * `sendInformativeUpdate()`, `sendTextChunk()`, `sendTextChunk()`, ..., `endStream()`.
+ *
+ * Once `endStream()` is called, the stream is considered ended and no further updates can be sent.
+ */
+export class StreamingResponse {
+  private readonly _context: TurnContext
+  private _nextSequence: number = 1
+  private _streamId?: string
+  private _message: string = ''
+  private _attachments?: Attachment[]
+  private _ended = false
+
+  // Queue for outgoing activities
+  private _queue: Array<() => Activity> = []
+  private _queueSync: Promise<void> | undefined
+  private _chunkQueued = false
+
+  // Powered by AI feature flags
+  private _enableFeedbackLoop = false
+  private _feedbackLoopType?: 'default' | 'custom'
+  private _enableGeneratedByAILabel = false
+  private _citations?: ClientCitation[] = []
+  private _sensitivityLabel?: SensitivityUsageInfo
+
+  /**
+     * Creates a new StreamingResponse instance.
+     * @param {TurnContext} context - Context for the current turn of conversation with the user.
+     * @returns {TurnContext} - The context for the current turn of conversation with the user.
+     */
+  public constructor (context: TurnContext) {
+    this._context = context
+  }
+
+  /**
+     * Gets the stream ID of the current response.
+     * @returns {string | undefined} - The stream ID of the current response.
+     * @remarks
+     * Assigned after the initial update is sent.
+     */
+  public get streamId (): string | undefined {
+    return this._streamId
+  }
+
+  /**
+     * Gets the citations of the current response.
+     */
+  public get citations (): ClientCitation[] | undefined {
+    return this._citations
+  }
+
+  /**
+     * Gets the number of updates sent for the stream.
+     * @returns {number} - The number of updates sent for the stream.
+     */
+  public get updatesSent (): number {
+    return this._nextSequence - 1
+  }
+
+  /**
+     * Queues an informative update to be sent to the client.
+     * @param {string} text Text of the update to send.
+     */
+  public queueInformativeUpdate (text: string): void {
+    if (this._ended) {
+      throw new Error('The stream has already ended.')
+    }
+
+    // Queue a typing activity
+    this.queueActivity(() => Activity.fromObject({
+      type: 'typing',
+      text,
+      channelData: {
+        streamType: 'informative',
+        streamSequence: this._nextSequence++
+      } as StreamingChannelData
+    }))
+  }
+
+  /**
+     * Queues a chunk of partial message text to be sent to the client
+     * @remarks
+     * The text we be sent as quickly as possible to the client. Chunks may be combined before
+     * delivery to the client.
+     * @param {string} text Partial text of the message to send.
+     * @param {Citation[]} citations Citations to be included in the message.
+     */
+  public queueTextChunk (text: string, citations?: Citation[]): void {
+    if (this._ended) {
+      throw new Error('The stream has already ended.')
+    }
+
+    // Update full message text
+    this._message += text
+
+    // If there are citations, modify the content so that the sources are numbers instead of [doc1], [doc2], etc.
+    this._message = Utilities.formatCitationsResponse(this._message)
+
+    // Queue the next chunk
+    this.queueNextChunk()
+  }
+
+  /**
+     * Ends the stream by sending the final message to the client.
+     * @returns {Promise<void>} - A promise representing the async operation
+     */
+  public endStream (): Promise<void> {
+    if (this._ended) {
+      throw new Error('The stream has already ended.')
+    }
+
+    // Queue final message
+    this._ended = true
+    this.queueNextChunk()
+
+    // Wait for the queue to drain
+    return this.waitForQueue()
+  }
+
+  /**
+     * Sets the attachments to attach to the final chunk.
+     * @param attachments List of attachments.
+     */
+  public setAttachments (attachments: Attachment[]): void {
+    this._attachments = attachments
+  }
+
+  /**
+     * Sets the sensitivity label to attach to the final chunk.
+     * @param sensitivityLabel The sensitivty label.
+     */
+  public setSensitivityLabel (sensitivityLabel: SensitivityUsageInfo): void {
+    this._sensitivityLabel = sensitivityLabel
+  }
+
+  /**
+     * Sets the citations for the full message.
+     * @param {Citation[]} citations Citations to be included in the message.
+     */
+  public setCitations (citations: Citation[]): void {
+    if (citations.length > 0) {
+      if (!this._citations) {
+        this._citations = []
+      }
+      let currPos = this._citations.length
+
+      for (const citation of citations) {
+        const clientCitation: ClientCitation = {
+          '@type': 'Claim',
+          position: currPos + 1,
+          appearance: {
+            '@type': 'DigitalDocument',
+            name: citation.title || `Document #${currPos + 1}`,
+            abstract: Utilities.snippet(citation.content, 477)
+          }
+        }
+        currPos++
+        this._citations.push(clientCitation)
+      }
+    }
+  }
+
+  /**
+     * Sets the Feedback Loop in Teams that allows a user to
+     * give thumbs up or down to a response.
+     * Default is `false`.
+     * @param enableFeedbackLoop If true, the feedback loop is enabled.
+     */
+  public setFeedbackLoop (enableFeedbackLoop: boolean): void {
+    this._enableFeedbackLoop = enableFeedbackLoop
+  }
+
+  /**
+     * Sets the type of UI to use for the feedback loop.
+     * @param feedbackLoopType The type of the feedback loop.
+     */
+  public setFeedbackLoopType (feedbackLoopType: 'default' | 'custom'): void {
+    this._feedbackLoopType = feedbackLoopType
+  }
+
+  /**
+     * Sets the the Generated by AI label in Teams
+     * Default is `false`.
+     * @param enableGeneratedByAILabel If true, the label is added.
+     */
+  public setGeneratedByAILabel (enableGeneratedByAILabel: boolean): void {
+    this._enableGeneratedByAILabel = enableGeneratedByAILabel
+  }
+
+  /**
+     * Returns the most recently streamed message.
+     * @returns The streamed message.
+     */
+  public getMessage (): string {
+    return this._message
+  }
+
+  /**
+     * Waits for the outgoing activity queue to be empty.
+     * @returns {Promise<void>} - A promise representing the async operation.
+     */
+  public waitForQueue (): Promise<void> {
+    return this._queueSync || Promise.resolve()
+  }
+
+  /**
+     * Queues the next chunk of text to be sent to the client.
+     * @private
+     */
+  private queueNextChunk (): void {
+    // Are we already waiting to send a chunk?
+    if (this._chunkQueued) {
+      return
+    }
+
+    // Queue a chunk of text to be sent
+    this._chunkQueued = true
+    this.queueActivity(() => {
+      this._chunkQueued = false
+      if (this._ended) {
+        // Send final message
+        return Activity.fromObject({
+          type: 'message',
+          text: this._message,
+          attachments: this._attachments,
+          channelData: {
+            streamType: 'final'
+          } as StreamingChannelData
+        })
+      } else {
+        // Send typing activity
+        return Activity.fromObject({
+          type: 'typing',
+          text: this._message,
+          channelData: {
+            streamType: 'streaming',
+            streamSequence: this._nextSequence++
+          } as StreamingChannelData
+        })
+      }
+    })
+  }
+
+  /**
+     * Queues an activity to be sent to the client.
+     */
+  private queueActivity (factory: () => Activity): void {
+    this._queue.push(factory)
+
+    // If there's no sync in progress, start one
+    if (!this._queueSync) {
+      this._queueSync = this.drainQueue().catch((err) => {
+        console.error(`Error occured when sending activity while streaming: "${err}".`)
+        throw err
+      })
+    }
+  }
+
+  /**
+     * Sends any queued activities to the client until the queue is empty.
+     * @returns {Promise<void>} - A promise that will be resolved once the queue is empty.
+     * @private
+     */
+  private async drainQueue (): Promise<void> {
+    // eslint-disable-next-line no-async-promise-executor
+    return new Promise<void>(async (resolve, reject) => {
+      try {
+        while (this._queue.length > 0) {
+          // Get next activity from queue
+          const factory = this._queue.shift()!
+          const activity = factory()
+
+          // Send activity
+          await this.sendActivity(activity)
+        }
+
+        resolve()
+      } catch (err) {
+        reject(err)
+      } finally {
+        // Queue is empty, mark as idle
+        this._queueSync = undefined
+      }
+    })
+  }
+
+  /**
+     * Sends an activity to the client and saves the stream ID returned.
+     * @param {Activity} activity - The activity to send.
+     * @returns {Promise<void>} - A promise representing the async operation.
+     * @private
+     */
+  private async sendActivity (activity: Activity): Promise<void> {
+    // Set activity ID to the assigned stream ID
+    if (this._streamId) {
+      activity.id = this._streamId
+      activity.channelData = Object.assign({}, activity.channelData, { streamId: this._streamId })
+    }
+
+    activity.entities = [
+      {
+        type: 'streaminfo',
+        ...activity.channelData
+      } as Entity
+    ]
+
+    if (this._citations && this._citations.length > 0 && !this._ended) {
+      // Filter out the citations unused in content.
+      const currCitations = Utilities.getUsedCitations(this._message, this._citations) ?? undefined
+      activity.entities.push({
+        type: 'https://schema.org/Message',
+        '@type': 'Message',
+        '@context': 'https://schema.org',
+        '@id': '',
+        citation: currCitations
+      } as unknown as Entity)
+    }
+
+    // Add in Powered by AI feature flags
+    if (this._ended) {
+      if (this._enableFeedbackLoop && this._feedbackLoopType) {
+        activity.channelData = Object.assign({}, activity.channelData, {
+          feedbackLoop: { type: this._feedbackLoopType }
+        })
+      } else {
+        activity.channelData = Object.assign({}, activity.channelData, {
+          feedbackLoopEnabled: this._enableFeedbackLoop
+        })
+      }
+
+      // Add in Generated by AI
+      if (this._enableGeneratedByAILabel) {
+        activity.entities.push({
+          type: 'https://schema.org/Message',
+          '@type': 'Message',
+          '@context': 'https://schema.org',
+          '@id': '',
+          additionalType: ['AIGeneratedContent'],
+          citation: this._citations && this._citations.length > 0 ? this._citations : [],
+          usageInfo: this._sensitivityLabel
+        } as unknown as Entity)
+      }
+    }
+
+    // Send activity
+    const response = await this._context.sendActivity(activity)
+    // await new Promise((resolve) => setTimeout(resolve, 1500))
+
+    // Save assigned stream ID
+    if (!this._streamId) {
+      this._streamId = response?.id
+    }
+  }
+}
+
+/**
+ * @private
+ * Structure of the outgoing channelData field for streaming responses.
+ * @remarks
+ * The expected sequence of streamTypes is:
+ *
+ * `informative`, `streaming`, `streaming`, ..., `final`.
+ *
+ * Once a `final` message is sent, the stream is considered ended.
+ */
+interface StreamingChannelData {
+  /**
+     * The type of message being sent.
+     * @remarks
+     * `informative` - An informative update.
+     * `streaming` - A chunk of partial message text.
+     * `final` - The final message.
+     */
+  streamType: 'informative' | 'streaming' | 'final';
+
+  /**
+     * Sequence number of the message in the stream.
+     * @remarks
+     * Starts at 1 for the first message and increments from there.
+     */
+  streamSequence: number;
+
+  /**
+     * ID of the stream.
+     * @remarks
+     * Assigned after the initial update is sent.
+     */
+  streamId?: string;
+}