@arcgis/ai-components 5.1.0-next.126 → 5.1.0-next.128

package/dist/utils/index.d.ts

@@ -7,10 +7,14 @@ import type { StructuredToolInterface } from "@langchain/core/tools";
 import type { AnnotationRoot, BaseChannel, StateGraph } from "@langchain/langgraph/web";
 import type { ChatOpenAI } from "@langchain/openai";
 import type { ZodType } from "zod";
+import type { AgentRegistration as AgentRegistration2 } from "../orchestrator/registry/agentRegistry.js";
 
 export { type CustomConfigurableType } from "../orchestrator";
 export { Orchestrator } from "../orchestrator";
 
+/** @internal */
+export type ChatModelTier = "advanced" | "default" | "fast";
+
 /**
  * Represents the chat message history between the user and the assistant, including all messages sent and received during the conversation.
  * This structure is used to provide context for the assistant's responses and can be utilized when invoking prompts to ensure the model
@@ -309,10 +313,21 @@ export function sendTraceMessage(data: TraceEventData, config?: RunnableConfig):
  */
 export function getEmbeddings(inputs: string[]): Promise<number[][]>;
 
+/**
+ * Calculates the cosine similarity between two numeric vectors. This is used to measure the similarity
+ * between two embedding vectors, where a score of 1 indicates identical vectors, 0 indicates orthogonal
+ * vectors, and -1 indicates opposite vectors.
+ *
+ * @param vectorA - The first vector array.
+ * @param vectorB - The second vector array.
+ * @returns A similarity score from -1 (opposite) to 1 (identical).
+ */
+export function cosineSimilarity(vectorA: number[], vectorB: number[]): number;
+
 /**
  * The suggestions emitted by the agent to the user interface.
  *
- * @internal
+ * @since 5.1
  */
 export type UXSuggestion = {
   /** The type of suggestion being made. */
@@ -324,32 +339,41 @@ export type UXSuggestion = {
 /**
  * Execution status returned by an agent run.
  *
- * @internal
+ * @since 5.1
  */
 export type AgentStatus = "failed" | "success" | "unknown";
 
 /**
  * Summary of a previously executed agent step.
  *
- * @internal
+ * @since 5.1
  */
 export interface PriorStep {
+  /** The agent that handled the step. */
   agentId: string;
+  /** The task assigned to the agent for this step. */
   assignedTask: string;
+  /** A brief summary of the step's execution. */
   summary: string;
+  /** The execution status of the step. */
   status: AgentStatus;
 }
 
 /**
  * Runtime execution context available to agent graph nodes and tools.
  *
- * @internal
+ * @since 5.1
  */
 export interface AgentExecutionContext<TState extends Record<string, unknown> = Record<string, unknown>> {
+  /** The user's original request. */
   userRequest: string;
+  /** The task assigned to the agent. */
   assignedTask: string;
+  /** The message history for the run */
   messages: ChatHistory;
+  /** Previous steps */
   priorSteps: PriorStep[];
+  /** Shared state available to the agent. */
   sharedState: SharedState<TState>;
 }
 
@@ -381,7 +405,7 @@ export type DataExplorationContext = {
 export const HelpAgent: AgentRegistration;
 
 /** @internal */
-export const ArcgisKnowledgeAgent: AgentRegistration;
+export const ArcgisKnowledgeAgent: AgentRegistration2;
 
 /** @internal */
 export type ArcgisKnowledgeContext = {
@@ -420,6 +444,9 @@ export const createWebmapEmbeddings: (mapView: MapView) => Promise<{
     }>;
 }>;
 
+/** @internal */
+export type GetContext<TContext extends Record<string, unknown>> = () => Promise<TContext> | TContext;
+
 /** @internal */
 export interface AgentWithContext<TContext extends Record<string, unknown> = Record<string, unknown>> {
   agent: AgentRegistration;
@@ -431,37 +458,9 @@ export interface AgentWithContext<TContext extends Record<string, unknown> = Rec
 }
 
 /** @internal */
-export function createAgentRuntimeState<TState extends Record<string, unknown> = Record<string, unknown>>(): StatelessAgentBaseState<TState>;
-
-/** @internal */
-export function createAgentRuntimeStateWithSharedState<TState extends Record<string, unknown> = Record<string, unknown>>(): StatefulAgentBaseState<TState>;
-
-/**
- * @param suggestion
- * @param config
- * @internal
- */
-export function sendUXSuggestion(suggestion: UXSuggestion, config?: RunnableConfig): Promise<void>;
+export type AgentExecutionContextWithSharedState<TState extends Record<string, unknown> = Record<string, unknown>> = AgentExecutionContext<TState>;
 
 /** @internal */
-export type SharedStatePatch<T extends Record<string, unknown> = Record<string, unknown>> = {
-    [K in keyof T]?: SharedStatePatchEntry<T[K]>;
-};
-
-/**
- * @param parameter0
- * @internal
- */
-export function createChatModel(parameter0?: {
-    modelTier?: ChatModelTier;
-    temperature?: number;
-    abortSignal?: AbortSignal;
-}): Promise<ChatOpenAI>;
-
-export type ChatModelTier = "advanced" | "default" | "fast";
-
-export type GetContext<TContext extends Record<string, unknown>> = () => Promise<TContext> | TContext;
-
 export type StatelessAgentBaseState<TState extends Record<string, unknown> = Record<string, unknown>> = {
   agentExecutionContext: BaseChannel<AgentExecutionContextWithSharedState<TState>, unknown, unknown>;
   outputMessage: BaseChannel<string, unknown, unknown>;
@@ -469,27 +468,76 @@ export type StatelessAgentBaseState<TState extends Record<string, unknown> = Rec
   status: BaseChannel<AgentStatus | undefined, unknown, unknown>;
 };
 
+/** @internal */
 export type StatefulAgentBaseState<TState extends Record<string, unknown> = Record<string, unknown>> = StatelessAgentBaseState<TState>
   & {
   sharedStatePatch: BaseChannel<SharedStatePatch<TState> | undefined, unknown, unknown>;
 };
 
-/** Patch shape returned by agents. `meta` is intentionally omitted. */
-export type SharedStatePatchEntry<T = unknown> = {
-  value: T;
-};
+/**
+ * Creates the standard runtime state for a custom agent graph.
+ * Includes common fields used by the assistant flow (request context, output message, summary, and status), so you only add your agent-specific state.
+ *
+ * @since 5.1
+ */
+export function createAgentRuntimeState<TState extends Record<string, unknown> = Record<string, unknown>>(): StatelessAgentBaseState<TState>;
 
-export type SharedState<T extends Record<string, unknown> = Record<string, unknown>> = {
-    [K in keyof T]?: SharedStateEntry<T[K]>;
-};
+/**
+ * Creates the standard runtime state for a custom agent graph, plus support for shared state updates.
+ * Use this when your agent needs to write values that other agents can read later in the same orchestration flow.
+ *
+ * @since 5.1
+ */
+export function createAgentRuntimeStateWithSharedState<TState extends Record<string, unknown> = Record<string, unknown>>(): StatefulAgentBaseState<TState>;
 
-export type AgentExecutionContextWithSharedState<TState extends Record<string, unknown> = Record<string, unknown>> = AgentExecutionContext<TState>;
+/**
+ * Sends an optional UX suggestion from an agent run to the host application.
+ * Use this for non-blocking hints (for example, recommended next actions or UI prompts) that the app may choose to display.
+ *
+ * @param suggestion
+ * @param config
+ * @since 5.1
+ */
+export function sendUXSuggestion(suggestion: UXSuggestion, config?: RunnableConfig): Promise<void>;
 
-/** Stored shared state entry. `meta` is added by the orchestrator. */
+/** @internal */
 export type SharedStateEntry<T = unknown> = {
   value: T;
   meta: {
       updatedByAgentId: string;
       updatedAt: number;
   };
-};
+};
+
+/** @internal */
+export type SharedStatePatchEntry<T = unknown> = {
+  value: T;
+};
+
+/**
+ * Shared state that can be read and updated during agent execution.
+ *
+ * @since 5.1
+ */
+export type SharedState<T extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof T]?: SharedStateEntry<T[K]>;
+};
+
+/**
+ * Partial shared state returned by an agent for merging into the current run state.
+ *
+ * @since 5.1
+ */
+export type SharedStatePatch<T extends Record<string, unknown> = Record<string, unknown>> = {
+    [K in keyof T]?: SharedStatePatchEntry<T[K]>;
+};
+
+/**
+ * @param parameter0
+ * @internal
+ */
+export function createChatModel(parameter0?: {
+    modelTier?: ChatModelTier;
+    temperature?: number;
+    abortSignal?: AbortSignal;
+}): Promise<ChatOpenAI>;

package/dist/utils/index.js

@@ -1,101 +1,115 @@
 /* COPYRIGHT Esri - https://js.arcgis.com/5.1/LICENSE.txt */
 import { g as p } from "../chunks/orchestrator.js";
-import { O as ge } from "../chunks/orchestrator.js";
-import { g as A, a as h, W as v, f as g, l as f, d as S, m as w, b as $, e as b, i as L, h as P, j as E, s as T, k as R, n as k, c as D, o as W } from "../chunks/generateLayerDescriptions.js";
-import x from "@arcgis/core/layers/FeatureLayer.js";
-import * as F from "@arcgis/core/core/reactiveUtils.js";
-import { N as M } from "../chunks/navigationGraph.js";
+import { O as ye } from "../chunks/orchestrator.js";
+import { g as h, a as A, W as S, f, l as y, d as v, m as w, b as $, e as b, i as E, h as L, j as P, s as M, k as T, n as R, c as k, o as x } from "../chunks/generateLayerDescriptions.js";
+import D from "@arcgis/core/layers/FeatureLayer.js";
+import * as W from "@arcgis/core/core/reactiveUtils.js";
+import { N as F } from "../chunks/navigationGraph.js";
 import { L as C } from "../chunks/layerStylingGraph.js";
 import { D as N } from "../chunks/dataExplorationGraph.js";
 import { H as z } from "../chunks/helpGraph.js";
 import { A as H } from "../chunks/arcgisKnowledgeGraph.js";
-const I = async (t) => {
-  const e = t.allLayers.toArray(), s = [], o = /* @__PURE__ */ new Map();
-  for (const a of e)
-    if (a instanceof x) {
+const I = async (e) => {
+  const t = e.allLayers.toArray(), s = [], n = /* @__PURE__ */ new Map();
+  for (const a of t)
+    if (a instanceof D) {
       const m = (async () => {
-        const r = await A(a), c = await h(a, r);
-        o.set(a.id, { layerItem: c, fieldRegistry: r });
+        const o = await h(a), r = await A(a, o);
+        n.set(a.id, { layerItem: r, fieldRegistry: o });
       })();
       s.push(m);
     }
-  return await Promise.all(s), o;
-}, O = async (t) => {
-  await F.whenOnce(() => t.ready);
-  const e = await I(t.map), { layers: s } = await U(e), o = {
+  return await Promise.all(s), n;
+}, O = async (e) => {
+  await W.whenOnce(() => e.ready);
+  const t = await I(e.map), { layers: s } = await U(t), n = {
     schemaVersion: b,
     modified: Date.now(),
     embeddings: {
       modelProvider: $,
       model: w,
-      dimensions: S,
+      dimensions: v,
       templates: {
-        layer: f,
-        field: g
+        layer: y,
+        field: f
       }
     },
     layers: s
-  }, a = v.safeParse(o);
+  }, a = S.safeParse(n);
   if (!a.success)
     throw console.error("Schema Mismatch:", a.error.format()), new Error("Webmap embedding generation failed validation.");
   return a.data;
-}, U = async (t) => {
-  const e = [], s = [];
-  for (const [r, { fieldRegistry: c, layerItem: n }] of t.entries()) {
-    const y = l(f, {
-      name: n.name,
-      title: n.title,
-      description: n.description
+}, U = async (e) => {
+  const t = [], s = [];
+  for (const [o, { fieldRegistry: r, layerItem: i }] of e.entries()) {
+    const l = g(y, {
+      name: i.name,
+      title: i.title,
+      description: i.description
     });
-    e.push(y);
+    t.push(l);
     const d = {
-      id: r,
-      name: n.name ?? "",
-      title: n.title,
-      description: n.description,
+      id: o,
+      name: i.name ?? "",
+      title: i.title,
+      description: i.description,
       vector: [],
       fields: []
     };
-    for (const [, i] of c.entries()) {
-      const u = l(g, {
-        name: i.name,
-        alias: i.alias,
-        description: i.description
+    for (const [, c] of r.entries()) {
+      const u = g(f, {
+        name: c.name,
+        alias: c.alias,
+        description: c.description
       });
-      e.push(u), d.fields.push({
-        name: i.name,
-        alias: i.alias,
-        description: i.description,
+      t.push(u), d.fields.push({
+        name: c.name,
+        alias: c.alias,
+        description: c.description,
         vector: []
       });
     }
     s.push(d);
   }
-  const o = await p(e);
+  const n = await p(t);
   let a = 0;
-  return { layers: s.map((r) => (r.vector = o[a++], r.fields.forEach((c) => {
-    c.vector = o[a++];
-  }), r)) };
-}, l = (t, e) => t.replace(/\{(\w+)\}/gu, (s, o) => e[o] ?? ""), J = P, Q = L, Y = E, Z = T, ee = p, te = M, ae = C, se = N, oe = z, re = H, ne = O, ie = () => R(), ce = () => k(), me = async (t, e) => await W(t, e), de = async ({
-  modelTier: t = "default",
-  temperature: e = 0,
+  return { layers: s.map((o) => (o.vector = n[a++], o.fields.forEach((r) => {
+    r.vector = n[a++];
+  }), o)) };
+}, g = (e, t) => e.replace(/\{(\w+)\}/gu, (s, n) => t[n] ?? ""), V = (e, t) => {
+  if (e.length !== t.length)
+    throw new Error("Vectors must be the same length");
+  let s = 0, n = 0, a = 0;
+  for (let r = 0; r < e.length; ++r) {
+    const i = e[r], l = t[r];
+    s += i * l, n += i * i, a += l * l;
+  }
+  const m = Math.sqrt(n * a);
+  if (m === 0)
+    return 0;
+  const o = s / m;
+  return Math.max(-1, Math.min(1, o));
+}, Q = L, Y = E, Z = P, ee = M, te = p, ae = V, se = F, ne = C, oe = N, re = z, ie = H, ce = O, me = () => T(), le = () => R(), de = async (e, t) => await x(e, t), ge = async ({
+  modelTier: e = "default",
+  temperature: t = 0,
   abortSignal: s
-} = {}) => await D({ modelTier: t, temperature: e, abortSignal: s });
+} = {}) => await k({ modelTier: e, temperature: t, abortSignal: s });
 export {
-  re as ArcgisKnowledgeAgent,
-  se as DataExplorationAgent,
-  oe as HelpAgent,
-  ae as LayerStylingAgent,
-  te as NavigationAgent,
-  ge as Orchestrator,
-  ie as createAgentRuntimeState,
-  ce as createAgentRuntimeStateWithSharedState,
-  de as createChatModel,
-  ne as createWebmapEmbeddings,
-  ee as getEmbeddings,
-  Q as invokeStructuredPrompt,
-  J as invokeTextPrompt,
-  Y as invokeToolPrompt,
-  Z as sendTraceMessage,
-  me as sendUXSuggestion
+  ie as ArcgisKnowledgeAgent,
+  oe as DataExplorationAgent,
+  re as HelpAgent,
+  ne as LayerStylingAgent,
+  se as NavigationAgent,
+  ye as Orchestrator,
+  ae as cosineSimilarity,
+  me as createAgentRuntimeState,
+  le as createAgentRuntimeStateWithSharedState,
+  ge as createChatModel,
+  ce as createWebmapEmbeddings,
+  te as getEmbeddings,
+  Y as invokeStructuredPrompt,
+  Q as invokeTextPrompt,
+  Z as invokeToolPrompt,
+  ee as sendTraceMessage,
+  de as sendUXSuggestion
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/ai-components",
-  "version": "5.1.0-next.126",
+  "version": "5.1.0-next.128",
   "description": "ArcGIS AI Components",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,16 +44,16 @@
     "@langchain/openai": "^1.4.3",
     "langchain": "^1.3.1",
     "lit": "^3.3.0",
-    "marked": "~18.0.4",
+    "marked": "~18.0.5",
     "tslib": "^2.8.1",
     "zod": "^4.3.6",
-    "@arcgis/lumina": "5.1.0-next.126",
-    "@arcgis/toolkit": "5.1.0-next.126"
+    "@arcgis/lumina": "5.1.0-next.128",
+    "@arcgis/toolkit": "5.1.0-next.128"
   },
   "peerDependencies": {
     "@arcgis/core": "^5.1.0-next",
     "@esri/calcite-components": "^5.1.1-next.3",
-    "@arcgis/map-components": "~5.1.0-next.126"
+    "@arcgis/map-components": "~5.1.0-next.128"
   },
   "css.customData": [
     "dist/docs/vscode.css-custom-data.json"