@arcgis/ai-components 5.2.0-next.99 → 6.0.0-next.1

package/dist/orchestrator/embeddings/webmapEmbeddings.js

@@ -0,0 +1,141 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import T from "@arcgis/core/layers/FeatureLayer.js";
+import r from "zod";
+import { g as u, W as F, f as v, l as h, d as I, m as A, a as x, s as S } from "../../chunks/webmapSchema.js";
+import { invokeStructuredPrompt as D } from "../models/prompts.js";
+import { getEmbeddings as P } from "./getEmbeddings.js";
+import * as N from "@arcgis/core/core/reactiveUtils.js";
+const E = r.object({
+  name: r.string(),
+  description: r.string(),
+  valueType: r.string(),
+  alias: r.string()
+}), M = r.object({
+  fields: r.array(E)
+}), w = (e, i) => e.getFieldAlias(i) ?? void 0, f = (e, i) => w(e, i.name) ?? i.alias ?? "", R = (e, i) => {
+  const n = w(e, i.name);
+  return !!(n && n !== (i.alias ?? ""));
+};
+function y(e, i) {
+  const n = /* @__PURE__ */ new Map();
+  for (const t of e.fields) {
+    const s = i.fields.find((a) => a.name === t.name), c = f(e, t), o = R(e, t), l = {
+      name: t.name,
+      type: t.type,
+      alias: o ? c : s?.alias ?? c,
+      description: s?.description ?? t.description ?? "",
+      valueType: s?.valueType ?? t.valueType ?? "",
+      domain: e.getFieldDomain(t.name) ?? void 0
+    };
+    n.set(t.name, l);
+  }
+  return n;
+}
+const j = async (e) => {
+  const n = await u("field_descriptions_prompt"), t = e.fields.filter((o) => !(f(e, o) && o.description)).map((o) => {
+    const { name: l, type: a, description: d } = o, m = f(e, o);
+    return [`Name: ${l}`, `Type: ${a}`, `Alias: ${m}`, `Description: ${d ?? "N/A"}`].join(", ");
+  }).join(`
+`);
+  if (t.length === 0)
+    return y(e, { fields: [] });
+  const s = {
+    existingItemTitle: e.portalItem?.title,
+    existingItemDescription: e.portalItem?.description,
+    existingLayerTitle: e.title,
+    existingLayerDescription: e.portalItem?.description,
+    fieldInformation: t
+  }, c = await D({
+    promptText: n,
+    schema: M,
+    inputVariables: s
+  });
+  return y(e, c);
+}, _ = r.object({
+  title: r.string(),
+  description: r.string(),
+  name: r.string().nullable()
+}), z = async (e, i) => {
+  const t = await u("layer_descriptions_prompt"), s = Array.from(i.values()), c = {
+    fieldInformation: JSON.stringify(s, null, 2),
+    existingLayerTitle: e.title,
+    existingLayerDescription: e.portalItem?.description,
+    existingLayerSnippet: e.portalItem?.snippet,
+    layerGeometryType: e.geometryType
+  };
+  return { ...await D({
+    promptText: t,
+    schema: _,
+    inputVariables: c
+  }), name: e.title ?? null };
+}, V = async (e) => {
+  const i = e.allLayers.toArray(), n = [], t = /* @__PURE__ */ new Map();
+  for (const s of i)
+    if (s instanceof T) {
+      const c = (async () => {
+        const o = await j(s), l = await z(s, o);
+        t.set(s.id, { layerItem: l, fieldRegistry: o });
+      })();
+      n.push(c);
+    }
+  return await Promise.all(n), t;
+}, B = async (e) => {
+  await N.whenOnce(() => e.ready);
+  const i = await V(e.map), { layers: n } = await W(i), t = {
+    schemaVersion: S,
+    modified: Date.now(),
+    embeddings: {
+      modelProvider: x,
+      model: A,
+      dimensions: I,
+      templates: {
+        layer: h,
+        field: v
+      }
+    },
+    layers: n
+  }, s = F.safeParse(t);
+  if (!s.success)
+    throw console.error("Schema Mismatch:", s.error.format()), new Error("Webmap embedding generation failed validation.");
+  return s.data;
+}, W = async (e) => {
+  const i = [], n = [];
+  for (const [o, { fieldRegistry: l, layerItem: a }] of e.entries()) {
+    const d = g(h, {
+      name: a.name,
+      title: a.title,
+      description: a.description
+    });
+    i.push(d);
+    const m = {
+      id: o,
+      name: a.name ?? "",
+      title: a.title,
+      description: a.description,
+      vector: [],
+      fields: []
+    };
+    for (const [, p] of l.entries()) {
+      const b = g(v, {
+        name: p.name,
+        alias: p.alias,
+        description: p.description
+      });
+      i.push(b), m.fields.push({
+        name: p.name,
+        alias: p.alias,
+        description: p.description,
+        vector: []
+      });
+    }
+    n.push(m);
+  }
+  const t = await P(i);
+  let s = 0;
+  return { layers: n.map((o) => (o.vector = t[s++], o.fields.forEach((l) => {
+    l.vector = t[s++];
+  }), o)) };
+}, g = (e, i) => e.replace(/\{(\w+)\}/gu, (n, t) => i[t] ?? "");
+export {
+  B as createWebmapEmbeddings
+};

package/dist/orchestrator/embeddings/webmapSchema.d.ts

@@ -0,0 +1,50 @@
+import type { z } from "zod";
+
+/** @internal */
+export const schemaVersion: "0.1";
+
+/** @internal */
+export const dimensions: 1536;
+
+/** @internal */
+export const modelProvider: "openai";
+
+/** @internal */
+export const model: string;
+
+/** @internal */
+export const layerTemplate: "Name: {name}\nTitle: {title}\nDescription: {description}";
+
+/** @internal */
+export const fieldTemplate: "Name: {name}\nAlias: {alias}\nDescription: {description}";
+
+/** @internal */
+export const WebmapEmbeddingSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<typeof schemaVersion>;
+    modified: z.ZodNumber;
+    embeddings: z.ZodObject<{
+        modelProvider: z.ZodLiteral<typeof modelProvider>;
+        model: z.ZodLiteral<typeof model>;
+        dimensions: z.ZodLiteral<typeof dimensions>;
+        templates: z.ZodObject<{
+            layer: z.ZodDefault<z.ZodString>;
+            field: z.ZodDefault<z.ZodString>;
+        }>;
+    }>;
+    layers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        title: z.ZodCatch<z.ZodString>;
+        description: z.ZodCatch<z.ZodString>;
+        vector: z.ZodArray<z.ZodNumber>;
+        fields: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            alias: z.ZodCatch<z.ZodString>;
+            description: z.ZodCatch<z.ZodString>;
+            vector: z.ZodArray<z.ZodNumber>;
+        }>>;
+    }>>>;
+}>;
+
+/** @internal */
+export type WebmapEmbedding = z.infer<typeof WebmapEmbeddingSchema>;

package/dist/orchestrator/models/chatModel.d.ts

@@ -0,0 +1,22 @@
+/** Creates chat models configured for the ArcGIS AI Utility Service. */
+import type { ChatOpenAI } from "@langchain/openai";
+import type { RunnableConfig } from "@langchain/core/runnables";
+
+/** Available ArcGIS chat model tiers. */
+export type ChatModelTier = "advanced" | "default" | "fast";
+
+/** Options for creating an ArcGIS chat model. */
+export type CreateChatModelOptions = {
+  /** Model tier used for the chat model. */
+  modelTier?: ChatModelTier;
+  /** Optional LangChain runnable configuration. */
+  config?: RunnableConfig;
+};
+
+/**
+ * Creates a configured ChatOpenAI instance pointing to the ArcGIS Utility Service.
+ *
+ * @param opts - Model tier and optional runnable configuration.
+ * @returns The configured chat model.
+ */
+export function createChatModel(opts?: CreateChatModelOptions): Promise<ChatOpenAI>;

package/dist/orchestrator/models/chatModel.js

@@ -0,0 +1,19 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { ChatOpenAI as c } from "@langchain/openai";
+import { C as s } from "../../chunks/modelConfig.js";
+const l = async (t = {}) => {
+  const { modelTier: e = "default", config: a } = t, { getChatAIUtilityServiceUrl: i } = await import("../../chunks/aiUtilityService.js"), { createAuthenticatedFetch: o } = await import("../../chunks/fetchUtils.js"), r = s[e], n = await i(e);
+  return new c({
+    modelName: r,
+    apiKey: "dummy-key",
+    useResponsesApi: !0,
+    zdrEnabled: !0,
+    configuration: {
+      baseURL: n,
+      fetch: await o({ config: a, withCredentials: !0 })
+    }
+  });
+};
+export {
+  l as createChatModel
+};

package/dist/orchestrator/models/modelConfig.d.ts

@@ -0,0 +1,2 @@
+/** @internal */
+export type EmbeddingModelTier = "default";

package/dist/orchestrator/models/prompts.d.ts

@@ -0,0 +1,105 @@
+/** Invokes text, structured-output, and tool-calling prompts. */
+import type { RunnableConfig } from "@langchain/core/runnables";
+import type { ZodType } from "zod";
+import type { ChatHistory } from "../types.js";
+import type { StructuredToolInterface } from "@langchain/core/tools";
+import type { AIMessage } from "@langchain/core/messages";
+import type { ChatModelTier } from "./chatModel.js";
+
+/** Options for sending a prompt to an LLM. */
+export type ArcgisPromptOptions = {
+  /** The input prompt text to send to the model. */
+  promptText: string;
+  /**
+   * The model tier to use. See the following options:
+   *
+   * - `default` - The default model tier, suitable for most general-purpose use cases.
+   *   At v5.2, this tier uses the `gpt-6-sol` model.
+   * - `advanced` - A model tier for tasks that benefit from more advanced capabilities.
+   *   At v5.2, this tier uses the `gpt-6-astra` model.
+   * - `fast` - A model tier for tasks such as classification and summarization, where
+   *   faster responses are preferred.
+   *   At v5.2, this tier uses the `gpt-6-luna` model.
+   *
+   * The models available for each tier may change as models are released and retired by
+   * the model provider and may not align with the semantic versioning rules of the JS SDK.
+   * The same prompt may produce different results when a tier's model changes.
+   * Re-evaluate and adjust prompts, agent descriptions, and tool descriptions
+   * when updating the ArcGIS Maps SDK for JavaScript or when model updates occur.
+   */
+  modelTier?: ChatModelTier;
+  /**
+   * The chat history used to provide context for the prompt. This should include the recent messages
+   * exchanged between the user and the assistant that are necessary for the model to generate an
+   * informed response. Providing chat history can help the model understand the conversation context
+   * and produce more accurate and relevant responses.
+   */
+  messages?: ChatHistory;
+  /** Optional runnable configuration used to derive runtime values (for example, conversation id and abort signal). */
+  config?: RunnableConfig;
+  /**
+   * Input variables for the prompt. This can include any relevant variables related to the context
+   * provided to the agent. This may be necessary for determining tool parameters or for providing additional
+   * context to the model when generating a response.
+   */
+  inputVariables?: Record<string, unknown>;
+};
+
+/** Options when sending a prompt to an LLM that expects a structured response validated against a Zod schema. */
+export type ArcgisStructuredPromptOptions<T> = ArcgisPromptOptions
+  & {
+  /**
+   * A Zod schema that defines the expected structure of the model's response. For example, if the expected
+   * result from a prompt sent to an LLM is parameters for a tool function that executes specific JS SDK core
+   * API calls, the schema should define the structure of those parameters. This allows the response from the model
+   * to be validated and parsed according to the defined schema, ensuring type safety and consistency.
+   *
+   * @see [Zod documentation](https://zod.dev/api)
+   */
+  schema: ZodType<T>;
+};
+
+/**
+ * Options when sending a prompt to an LLM when the node is expected to invoke tools (e.g. functions defined
+ * in the client). This includes the array of tools that the model can choose to invoke in response to the prompt.
+ */
+export type ArcgisToolPromptOptions = ArcgisPromptOptions
+  & {
+  /**
+   * An array of tools that the model can choose to invoke in response to the prompt.
+   *
+   * @see [StructuredToolInterface documentation](https://reference.langchain.com/javascript/interfaces/_langchain_core.tools.StructuredToolInterface.html)
+   */
+  tools: StructuredToolInterface[];
+};
+
+/**
+ * Sends a prompt to an LLM and returns a plain text response. This function should be used when you expect
+ * a simple text response from the model without the need for structured parsing or tool invocation.
+ *
+ * @param opts - Options for the prompt, including the prompt text, model tier, chat history, and input variables.
+ * @returns The model response.
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
+ */
+export function invokeTextPrompt(opts: ArcgisPromptOptions): Promise<string>;
+
+/**
+ * Sends a prompt to an LLM and returns a structured response validated against a Zod schema.
+ *
+ * @param opts - Prompt options, including a Zod schema for response validation.
+ * @returns The model response parsed into the structure defined by the provided Zod schema.
+ * @see [Zod documentation](https://zod.dev/api)
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
+ */
+export function invokeStructuredPrompt<T>(opts: ArcgisStructuredPromptOptions<T>): Promise<T>;
+
+/**
+ * Invokes a prompt with tools enabled and returns the model's tool call response.
+ * This function does not execute the returned tool calls.
+ *
+ * @param opts - Prompt options, including an array of tools the model can invoke.
+ * @returns Resolves to the model's response as an AIMessage as defined in LangChain.
+ * @see [AIMessage documentation](https://reference.langchain.com/javascript/classes/_langchain_core.messages.AIMessage.html)
+ * @see [Custom agents guide](https://developers.arcgis.com/javascript/latest/agentic-apps/ai-custom-agents/)
+ */
+export function invokeToolPrompt(opts: ArcgisToolPromptOptions): Promise<AIMessage>;

package/dist/orchestrator/models/prompts.js

@@ -0,0 +1,46 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { SystemMessagePromptTemplate as f, ChatPromptTemplate as u } from "@langchain/core/prompts";
+import { createChatModel as l } from "./chatModel.js";
+import { isAIMessage as h, isToolMessage as g } from "@langchain/core/messages";
+const T = (s) => {
+  const a = /* @__PURE__ */ new Set();
+  for (const t of s)
+    if (h(t)) {
+      const e = t;
+      e.tool_calls && e.tool_calls.length > 0 && e.tool_calls.forEach((o) => {
+        o.id && a.add(o.id);
+      });
+    }
+  return s.filter((t) => {
+    if (g(t)) {
+      const e = t;
+      return a.has(e.tool_call_id);
+    }
+    return !0;
+  });
+}, p = (s, a) => {
+  const n = f.fromTemplate(s);
+  return u.fromMessages([n, ...a]);
+}, M = async (s) => {
+  const { promptText: a, modelTier: n, messages: t, config: e } = s, o = p(a, t ?? []), r = await l({ modelTier: n, config: e });
+  return o.pipe(r);
+}, x = async (s) => {
+  const { promptText: a, modelTier: n = "default", messages: t, inputVariables: e, config: o } = s, c = await (await M({
+    promptText: a,
+    modelTier: n,
+    messages: t,
+    config: o
+  })).invoke(e ?? {}, o);
+  return typeof c == "string" ? c : c.text;
+}, P = async (s) => {
+  const { promptText: a, modelTier: n = "default", messages: t, inputVariables: e, schema: o, config: r } = s, c = p(a, t ?? []), i = (await l({ modelTier: n, config: r })).withStructuredOutput(o);
+  return await c.pipe(i).invoke(e ?? {}, r);
+}, S = async (s) => {
+  const { promptText: a, modelTier: n = "default", messages: t, inputVariables: e, tools: o, config: r } = s, c = o.length > 0 ? T(t ?? []) : t ?? [], m = p(a, c), i = await l({ modelTier: n, config: r });
+  return await m.pipe(i.bindTools(o)).invoke(e ?? {}, r);
+};
+export {
+  P as invokeStructuredPrompt,
+  x as invokeTextPrompt,
+  S as invokeToolPrompt
+};

package/dist/orchestrator/orchestrator/orchestrator.d.ts

@@ -0,0 +1,75 @@
+import type View from "@arcgis/core/views/View.js";
+import type { AgentWithContext, AskOptions } from "../types.js";
+import type { OrchestratorEvent } from "./orchestratorEvents.js";
+
+/**
+ * Orchestrator initialization dependencies.
+ *
+ * @internal
+ */
+export type Deps = {
+  /** Optional map view enabling map-dependent services. */
+  view?: View;
+  /** Optional agents to register at init. */
+  agents?: AgentWithContext[];
+  /** Whether to emit normalized runtime span events. */
+  runtimeEventsEnabled?: boolean;
+};
+
+/**
+ * Orchestrator
+ *
+ * Coordinates chat-in / events-out workflows on top of LangGraph.
+ * - Accepts user input via `ask()`
+ * - Streams structured events (`trace`, `interrupt`, `completed`, `cancelled`)
+ * - Manages HITL (human-in-the-loop) flows and cancellation
+ *
+ * Intended as the main entrypoint for the UX layer.
+ *
+ * @internal
+ */
+export class Orchestrator {
+  /**
+   * Creates and returns an AI-ready Orchestrator instance.
+   *
+   * @param deps - Core dependencies (layer/field registry plus optional map views).
+   * @returns Ready Orchestrator.
+   */
+  static init(deps: Deps): Promise<Orchestrator>;
+  /**
+   * Run a new chat turn through the graph.
+   * Yields structured events for the UI to consume:
+   *  - `trace`: intermediate model output
+   *  - `interrupt`: HITL required, wait for `resumeInterrupt()`
+   *  - `completed`: final result with chat history + layer styling
+   *  - `cancelled`: user aborted the run
+   *
+   * @param userInput - User request to process.
+   * @param options - Agent selection and routing behavior and locale for this run.
+   */
+  ask(userInput: string, options?: AskOptions): AsyncGenerator<OrchestratorEvent>;
+  /**
+   * Cancels the active run.
+   *
+   * - Aborts in-flight work for consumers that honor AbortSignal.
+   * - Invalidates active stream iterators via epoch bump.
+   * - Unblocks any pending HITL wait.
+   */
+  cancel(): void;
+  /** Optional: allow UI to cancel the current HITL. */
+  cancelInterrupt(): void;
+  /**
+   * Disposes this instance by terminating the embeddings worker
+   * and cleaning up all related resources.
+   */
+  dispose(): void;
+  /** Start a new conversation by clearing chat history, prior steps, and shared state. */
+  newConversation(): void;
+  /**
+   * Generic resume for any HITL interrupt.
+   * The payload is whatever the UI collected (e.g. "yes", "no", layerId, etc).
+   *
+   * @param payload
+   */
+  resumeInterrupt(payload: unknown): void;
+}