@arcgis/ai-components 5.1.0-next.7 → 5.1.0-next.71

package/dist/components/arcgis-assistant/customElement.d.ts

@@ -1,27 +1,31 @@
 /// <reference path="../../index.d.ts" />
-import type Portal from "@arcgis/core/portal/Portal.js";
+import type Collection from "@arcgis/core/core/Collection.js";
 import type { PublicLitElement as LitElement } from "@arcgis/lumina";
+import type { AssistantMessage, AssistantPromptSelectDetail, ChatMessage, Interrupt } from "./types.js";
 import type { T9nMeta } from "@arcgis/lumina/controllers";
 import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/arcgis-map";
 
 /**
  * The ArcGIS Assistant component provides a chat-based natural language interface for interacting with
- * map data and services. This component relies on large language models to understand user prompts and
- * generate both text and structured responses based on the user's intent and the context of the map.
+ * web map data via agents. This component uses an orchestrator, which relies on a large language model (LLM)
+ * for determining user intent. Once the intent is determined, the assistant routes the user's request
+ * to an agent that uses an LLM to generate text and structured responses.
  *
  * By default, the `arcgis-assistant` component does not include any agents. You must register at least one
  * agent for the assistant to function. You can register agents declaratively using any of the
  * available agent components, or you can register custom agents.
  *
- * ## Register ArcGIS agents
+ * ## Register agents
  *
- * To register ArcGIS agents declaratively, include one or more of the following agent components as children
+ * To register agents declaratively, include one or more agent components as children
  * of the `arcgis-assistant` component. This can be done in HTML or programmatically using JavaScript.
  *
  * ```html
- * <arcgis-assistant>
+ * <arcgis-map id="my-map"></arcgis-map>
+ * <arcgis-assistant reference-element="#my-map">
  *   <arcgis-assistant-navigation-agent></arcgis-assistant-navigation-agent>
  *   <arcgis-assistant-data-exploration-agent></arcgis-assistant-data-exploration-agent>
+ *   <arcgis-assistant-help-agent></arcgis-assistant-help-agent>
  * </arcgis-assistant>
  * ```
  *
@@ -33,92 +37,228 @@ import type { ArcgisMap as ArcgisMap } from "@arcgis/map-components/components/a
  * assistant.appendChild(dataExplorationAgent);
  * ```
  *
- * To learn more about this component, try out the [demo](#demo) below.
+ * Note that the `reference-element` property on the `arcgis-assistant` component must point to a valid `arcgis-map` element
+ * for the included ArcGIS agents to function properly, as they rely on the map context to perform their tasks. This is not
+ * a requirement for [custom agents](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/).
  *
- * @slot  - This is the default slot
+ * ## Context
+ *
+ * Use the [referenceElement](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#referenceElement) property to provide a web map as context to the assistant and its agents.
+ * This should be a reference to the map that the assistant will interact with, and is required for the included ArcGIS
+ * agents to function properly.
+ *
+ * To learn more about this component, try out the [demo](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#demos)
+ *
+ * ## Important considerations and best practices
+ *
+ * Due to the non-deterministic nature of generative AI, there may be inaccuracies or unexpected behavior when using the
+ * out-of-the-box agents. Therefore, it is important to set clear expectations
+ * for end users and provide guidance on how to interact with the assistant to help mitigate these issues. Some ways to do this include:
+ *
+ * - Provide [suggestedPrompts](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#suggestedPrompts). This helps users understand the bounds of the assistant
+ * and gives them an idea of how to phrase questions to get the best results.
+ * - Use the [entryMessage](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#entryMessage) property to provide an entry message with instructions and guidance.
+ *
+ * @slot [header-actions-start] - Slot for adding actions to the start of the header.
  * @slot [header-actions-end] - Slot for adding actions to the end of the header.
+ * @slot [message-starter] - Slot for adding content before the message list.
+ * @slot [messages] - Slot for customizing the rendered message list.
+ * @slot [message-loading] - Slot for customizing the in-progress assistant loading state.
  * @slot [entry-message] - Slot for adding a welcome or entry message on load.
- * @slot [entry-actions-start] - Slot for adding actions to the start of the entry area.
- * @slot [footer-content] - Slot for adding content to the footer.
+ * @slot [interrupt] - Slot for customizing the interrupt UI.
+ * @slot [chat-entry] - Slot for customizing the chat entry UI.
+ * @slot [entry-actions-start] - Slot for adding actions to the start of the chat entry.
+ * @slot [entry-actions-end] - Slot for adding actions to the end of the chat entry.
+ * @slot [footer-content] - Slot for adding content below the chat entry.
  * @since 5.0
  * @beta
+ * @see [Intro to building agentic mapping applications](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-introduction/)
+ * @see [AI Assistant component sample](https://developers.arcgis.com/javascript/latest/sample-code/ai-assistant/)
  * @see [arcgis-assistant-data-exploration-agent](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant-data-exploration-agent/)
  * @see [arcgis-assistant-navigation-agent](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant-navigation-agent/)
+ * @see [arcgis-assistant-help-agent](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant-help-agent/)
  */
 export abstract class ArcgisAssistant extends LitElement {
   /** @internal */
-  protected _messages: { assistantLabel: string; } & T9nMeta<{ assistantLabel: string; }>;
+  protected _messages: {
+      assistantLabel: string;
+      stopButtonLabel: string;
+      askButtonLabel: string;
+  } & T9nMeta<{
+      assistantLabel: string;
+      stopButtonLabel: string;
+      askButtonLabel: string;
+  }>;
+  /** @default false */
+  get awaitingResponse(): boolean;
+  get awaitingResponseStep(): string;
+  /**
+   * When `true`, enables the copy action that, when clicked, copies the content of the message to the clipboard. This can be helpful for users to easily copy and share
+   * information provided by the assistant, such as a summary of findings, a set of instructions, or any other relevant details. Enabling this property can enhance the user experience by providing a convenient way for users to capture and utilize the information generated by the assistant.
+   *
+   * @default false
+   * @example
+   * ```html
+   * <arcgis-assistant copy-enabled></arcgis-assistant>
+   * ```
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.copyEnabled = true;
+   * ```
+   */
+  accessor copyEnabled: boolean;
   /**
    * The description text displayed below the heading in the assistant. This text provides additional
    * context about the assistant's capabilities and how users can interact with it.
    *
    * @example
    * ```html
-   * <arcgis-assistant description="Ask anything about your map data."></arcgis-assistant>
+   * <arcgis-assistant description="Explore parcel data ownership, zoning designations, and other relevant information."></arcgis-assistant>
    * ```
    * @example
    * ```js
    * const assistant = document.querySelector("arcgis-assistant");
-   * assistant.description = "Ask anything about your map data.";
+   * assistant.description = "Explore parcel data ownership, zoning designations, and other relevant information.";
    * ```
    */
   accessor description: string | undefined;
   /**
-   * The message to display when the assistant is first loaded.
+   * The instructions to display when the assistant is first loaded. This is intended to be a welcome or entry message that
+   * provides guidance to users on how to interact with the assistant. Once the user submits their first message,
+   * the entry message will be closed and replaced with the chat interface. You can use this property to provide
+   * instructions, suggest prompts, or simply welcome users to the assistant.
    *
    * @example
    * ```html
-   * <arcgis-assistant entry-message="Hello! How can I assist you with your map today?"></arcgis-assistant>
+   * <arcgis-assistant entry-message="I can answer questions about parcel ownership, zoning, and other relevant information."></arcgis-assistant>
    * ```
    * @example
    * ```js
    * const assistant = document.querySelector("arcgis-assistant");
-   * assistant.entryMessage = "Hello! How can I assist you with your map today?";
+   * assistant.entryMessage = "I can answer questions about parcel ownership, zoning, and other relevant information.";
    * ```
    */
   accessor entryMessage: string | undefined;
+  /**
+   * When `true`, enables the feedback action in the chat interface, allowing developers to capture user feedback on the assistant's responses.
+   * The action simply provides a thumbs up and thumbs down experience for users to indicate whether a response was helpful or not. When the
+   * user submits feedback, the [@arcgisFeedback](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#event-arcgisFeedback) event is emitted allowing the app developer to capture additional feedback
+   * through a custom interface and log it to a database or service for later analysis.
+   *
+   * @default false
+   * @example
+   * ```html
+   * <arcgis-assistant feedback-enabled></arcgis-assistant>
+   * ```
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.feedbackEnabled = true;
+   * assistant.addEventListener("arcgisFeedback", (event) => {
+   *   const feedback = event.detail;
+   *   // Capture additional feedback from the user and log it to a database or service for later analysis
+   * });
+   * ```
+   */
+  accessor feedbackEnabled: boolean;
   /**
    * The heading text displayed at the top of the assistant. This name should be concise and
    * descriptive of the assistant's purpose.
    *
+   * For applications where the primary interface is the assistant, this heading could also be used as the
+   * application title. In cases where the assistant could be collapsed or is a secondary interface to a standard
+   * GUI, the heading should be more specific to the assistant's function to avoid confusion with the overall
+   * application title.
+   *
    * @example
    * ```html
-   * <arcgis-assistant heading="Map Assistant"></arcgis-assistant>
+   * <arcgis-assistant heading="Parcel Viewer"></arcgis-assistant>
    * ```
    * @example
    * ```js
    * const assistant = document.querySelector("arcgis-assistant");
-   * assistant.heading = "Map Assistant";
+   * assistant.heading = "Zoning Assistant";
    * ```
    */
   accessor heading: string | undefined;
   /**
-   * The portal used for authentication and making requests to the LLM via proxy requests.
+   * The active interrupt, if the assistant is waiting for additional user input.
+   * Applications rendering custom interrupt UI through the `interrupt` slot can read this value
+   * and call [submitInterrupt()](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#submitInterrupt) or [cancelInterrupt()](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#cancelInterrupt)
+   * to respond.
+   */
+  get interrupt(): Interrupt | null;
+  /**
+   * When `true`, keeps suggested prompts displayed in the UI after the user submits a message. By default, suggested prompts are cleared,
+   * when the user submits a message.
    *
+   * @default false
+   * @example
+   * ```html
+   * <arcgis-assistant keep-suggested-prompts></arcgis-assistant>
+   * ```
    * @example
    * ```js
    * const assistant = document.querySelector("arcgis-assistant");
-   * assistant.portal = new Portal({ url: "https://www.arcgis.com" });
+   * assistant.keepSuggestedPrompts = true;
    * ```
    */
-  accessor portal: Portal;
+  accessor keepSuggestedPrompts: boolean;
+  /**
+   * When `true`, enables the log action that when clicked displays log messages in the chat interface. Log messages provide detailed messages including
+   * which agents or tools were invoked, the parameters generated by the LLM, and any relevant details about how the assistant arrived at its response.
+   * Enabling logs can be helpful for developers for debugging during the development of an assistant or agentic web application.
+   * It may also be useful to end users for transparency purposes, allowing them to understand the assistant's behavior and decision-making process.
+   *
+   * Enabling this property for a production app depends on the role of the audience. More technical audiences may benefit from having access to these
+   * logs while non-technical audiences may find them overwhelming or confusing.
+   *
+   * @default false
+   * @example
+   * ```html
+   * <arcgis-assistant log-enabled></arcgis-assistant>
+   * ```
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.logEnabled = true;
+   * ```
+   */
+  accessor logEnabled: boolean;
+  /**
+   * The collection of messages exchanged between the user and the assistant. Each message includes the role
+   * (user or assistant), along with any relevant logs or errors. These messages are rendered in the chat interface
+   * and are used to provide context for the conversation. When a user submits a message, it is added to this
+   * collection with the role of "user". When the assistant generates a response, it is added to this collection
+   * with the role of "assistant", along with any logs or errors that occurred during processing.
+   */
+  accessor messages: Collection<ChatMessage>;
+  /** @default false */
+  accessor readAloudEnabled: boolean;
   /**
    * The reference element to the map that provides context for the assistant and its agents. Currently,
-   * this is only scoped to `arcgis-map` elements, but may be extended to support other elements in
-   * the future.
+   * this is only scoped to `arcgis-map` elements. This is required when ArcGIS agents are registered to the assistant.
+   * For example, this allows the navigation agent to execute a map navigation tool for a specific map.
    *
    * @example
    * ```html
    * <arcgis-map id="my-map"></arcgis-map>
-   * <arcgis-assistant reference-element="#my-map"></arcgis-assistant>
+   * <arcgis-assistant reference-element="my-map"></arcgis-assistant>
    * ```
    */
   accessor referenceElement: ArcgisMap | string | null;
   /**
-   * Suggested prompts to display in the assistant on load. These are intended to help users get started
-   * with common queries or actions.You should typically provide 2-3 suggested prompts that are
-   * relevant to the context of the data being used and the capabilities of the registered agents.
+   * Prompts to suggest to the end user on load. These are intended to help users understand which questions they can ask.
+   * This property should be set to establish boundaries for the end user. As all agents have limitations and LLMs can
+   * be unpredictable, it's important to set clear expectations for users to give them a better chance to succeed.
+   * By providing suggested prompts, you can guide users towards asking questions that are relevant to the data being
+   * used and the capabilities of the registered agents, which can help to ensure that the assistant provides accurate
+   * and helpful responses.
+   *
+   * You should typically provide 2-3 suggested prompts.
    *
+   * @since 5.0
    * @example
    * ```js
    * const assistant = document.querySelector("arcgis-assistant");
@@ -129,4 +269,179 @@ export abstract class ArcgisAssistant extends LitElement {
    * ```
    */
   accessor suggestedPrompts: string[];
+  /** @default false */
+  accessor voiceInputEnabled: boolean;
+  /** Cancels the active interrupt, if one is pending. */
+  cancelInterrupt(): void;
+  /**
+   * Clears the chat history between the user and the assistant. This method can be used to programmatically reset the conversation,
+   * removing all messages from the chat interface.
+   *
+   * @since 5.0
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.clearChatHistory();
+   * ```
+   */
+  clearChatHistory(): Promise<void>;
+  /**
+   * Submits a response for the active interrupt.
+   *
+   * @param response - The response payload expected by the active interrupt type.
+   */
+  submitInterrupt(response: string[] | boolean | string): void;
+  /**
+   * Programmatically submits a message to the assistant. This method can be used to submit messages from outside the component,
+   * such as from another component or from custom JavaScript code. When a message is submitted using this method, it is added
+   * to the messages collection with the role of "user", and then processed by the assistant in the same way as if it were submitted
+   * through the chat interface. This allows for greater flexibility in how messages are sent to the assistant and can enable more
+   * complex interactions and integrations with other components or services.
+   *
+   * @param message - The message to submit to the assistant. This should be a string containing the user's input or question they want to ask the assistant.
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.submitMessage("What is the population of New York City?");
+   * ```
+   */
+  submitMessage(message: string): Promise<void>;
+  /**
+   * Emitted when the user cancels a message. This is typically invoked when a user submits a question while a previous question is still being processed.
+   * This allows app developers to capture messages cancelled by the user and respond to them in custom ways, such as by providing additional information,
+   * triggering other actions in the app, or logging them for analysis.
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisCancel", (event) => {
+   *   // Handle the cancelled message
+   * });
+   * ```
+   */
+  readonly arcgisCancel: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Emitted when the assistant encounters an error. The event detail includes an Error object with information about the error that occurred.
+   * This allows app developers to capture errors that occur within the assistant and respond to them in custom ways, such as by displaying an
+   * error message to the user, logging the error for analysis, or triggering other actions in the app.
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisError", (event) => {
+   *   const error = event.detail;
+   *   // Handle the error, such as by displaying an error message to the user or logging it for analysis
+   * });
+   * ```
+   */
+  readonly arcgisError: import("@arcgis/lumina").TargetedEvent<this, Error>;
+  /**
+   * Emitted when the user clicks the thumbs up or thumbs down feedback action that is displayed when [feedbackEnabled](https://developers.arcgis.com/javascript/latest/references/ai-components/components/arcgis-assistant/#feedbackEnabled) is `true`.
+   * The event detail includes an AssistantMessage object that includes a feedback property with an object indicating whether the feedback is positive or negative.
+   * This allows the application to capture user feedback on the assistant's responses and respond to it in custom ways, such as by providing additional
+   * information, adjusting the assistant's behavior, logging the feedback for analysis, or triggering other actions in the app.
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisFeedback", (event) => {
+   *   const feedback = event.detail;
+   *   // Handle the feedback, such as by providing additional information, adjusting the assistant's behavior, or logging it for analysis
+   * });
+   * ```
+   */
+  readonly arcgisFeedback: import("@arcgis/lumina").TargetedEvent<this, AssistantMessage>;
+  /**
+   * Emitted when an agent triggers an interrupt. An interrupt is a human-in-the-loop mechanism that provides a UI component prompting
+   * the user for additional information.
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisInterrupt", (event) => {
+   *   const interrupt = event.detail;
+   *   // Handle the interrupt
+   * });
+   * ```
+   */
+  readonly arcgisInterrupt: import("@arcgis/lumina").TargetedEvent<this, Interrupt>;
+  /**
+   * Emitted when the user cancels an interrupt. This is typically invoked when a user clicks the cancel button displayed in an interrupt message
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisInterruptCancel", (event) => {
+   *   // Handle the interrupt cancellation such as logging it for analysis
+   * });
+   * ```
+   */
+  readonly arcgisInterruptCancel: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Emitted when the user submits a message during an interrupt. For example, this will be invoked if the user clicks the submit button
+   * in an interrupt message asking for confirmation, or when the user submits additional text or selects an option provided in an interrupt.
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisInterruptSubmit", (event) => {
+   *   const message = event.detail; // The message or option selected by the user for the interrupt
+   *   // Do something with the interrupt submission
+   * });
+   * ```
+   */
+  readonly arcgisInterruptSubmit: import("@arcgis/lumina").TargetedEvent<this, string[] | boolean | string>;
+  /**
+   * Emitted when a suggested prompt is selected from the assistant UI.
+   * Applications that provide a custom `chat-entry` slot can listen for this event to sync
+   * the selected prompt into their own entry implementation.
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisPromptSelect", (event) => {
+   *   const { prompt } = event.detail;
+   *   // Sync prompt into a custom chat entry
+   * });
+   * ```
+   */
+  readonly arcgisPromptSelect: import("@arcgis/lumina").TargetedEvent<this, AssistantPromptSelectDetail>;
+  /**
+   * Emitted when the assistant is ready to receive messages from the end user. This indicates that the assistant has been successfully
+   * initialized and is ready to process user input.
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisReady", (event) => {
+   *   // Handle the assistant being ready, such as by hiding a loading indicator,
+   *   // displaying a welcome message, or enabling certain UI elements for user interaction
+   * });
+   * ```
+   */
+  readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
+  /**
+   * Emitted when the user submits a message. This is typically invoked when a user clicks the submit button in the chat interface or hits the Enter key.
+   *
+   * @example
+   * ```js
+   * const assistant = document.querySelector("arcgis-assistant");
+   * assistant.addEventListener("arcgisSubmit", (event) => {
+   *   const message = event.detail;
+   *   // Do something with the submitted message, such as logging it for analysis or triggering other actions in the app
+   * });
+   * ```
+   */
+  readonly arcgisSubmit: import("@arcgis/lumina").TargetedEvent<this, string>;
+  readonly "@eventTypes": {
+    arcgisCancel: ArcgisAssistant["arcgisCancel"]["detail"];
+    arcgisError: ArcgisAssistant["arcgisError"]["detail"];
+    arcgisFeedback: ArcgisAssistant["arcgisFeedback"]["detail"];
+    arcgisInterrupt: ArcgisAssistant["arcgisInterrupt"]["detail"];
+    arcgisInterruptCancel: ArcgisAssistant["arcgisInterruptCancel"]["detail"];
+    arcgisInterruptSubmit: ArcgisAssistant["arcgisInterruptSubmit"]["detail"];
+    arcgisPromptSelect: ArcgisAssistant["arcgisPromptSelect"]["detail"];
+    arcgisReady: ArcgisAssistant["arcgisReady"]["detail"];
+    arcgisSubmit: ArcgisAssistant["arcgisSubmit"]["detail"];
+  };
 }