@arcgis/ai-components 5.1.0-next.98 → 5.2.0-next.0

package/dist/chunks/helpGraph.js

@@ -0,0 +1,123 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { StateGraph as d, START as g, END as i } from "@langchain/langgraph/web";
+import { l as h, g as x, f as p, r as f, t as y, H as u } from "./adapter.js";
+import "@arcgis/core/identity/IdentityManager.js";
+import "@arcgis/core/portal/Portal.js";
+import { j as S, s as c } from "./generateLayerDescriptions.js";
+import "@langchain/core/messages";
+import "@langchain/core/callbacks/dispatch/web";
+import "@langchain/openai";
+import "@arcgis/core/core/reactiveUtils.js";
+import "@arcgis/core/layers/FeatureLayer.js";
+import "@arcgis/core/request.js";
+import { ToolNode as E } from "@langchain/langgraph/prebuilt";
+import "@langchain/core/prompts";
+const m = [h], v = (e) => {
+  if (!e || e.size === 0)
+    return "No layers available in this map.";
+  const t = Array.from(e.values()).map(({ layerItem: r, fieldRegistry: s }, l) => {
+    const a = Array.from(s.values()).map((n) => n.name).slice(0, 10).join(", "), o = s.size > 10 ? ` (and ${s.size - 10} more)` : "";
+    return `${l + 1}. "${r.title}". Description: ${r.description}
+   Fields: ${a}${o}`;
+  }).join(`
+
+`);
+  return `This map contains ${e.size} layer(s):
+
+${t}`;
+}, T = (e) => {
+  const t = e?.list() ?? [];
+  return t.length ? t.map((r) => `- ${r.agent.name}: ${r.agent.description}`).join(`
+`) : "No agents currently available.";
+};
+async function _(e, t) {
+  const r = await x("help_prompt"), s = p(t, "layersAndFieldsRegistry"), l = p(t, "agentRegistry");
+  try {
+    const a = await S({
+      promptText: r,
+      modelTier: "fast",
+      tools: m,
+      inputVariables: {
+        layerSummary: v(s),
+        agents: T(l),
+        assignedTask: e.agentExecutionContext.assignedTask,
+        userRequest: e.agentExecutionContext.userRequest,
+        priorSteps: e.agentExecutionContext.priorSteps
+      }
+    }), o = (a.tool_calls?.length ?? 0) > 0, n = typeof a.text == "string" ? a.text.trim() : "";
+    return {
+      ...e,
+      helpInternalState: {
+        ...e.helpInternalState,
+        toolCallMessage: o ? a : void 0
+      },
+      outputMessage: o ? e.outputMessage : n,
+      summary: o ? "Prepared help tool call from assigned task." : "Provided map-related help based on the assigned task.",
+      status: o ? e.status : "success"
+    };
+  } catch (a) {
+    const o = a instanceof Error ? a.message : String(a);
+    return {
+      ...e,
+      outputMessage: `Error invoking help agent: ${o}`,
+      summary: "Help agent execution failed.",
+      status: "failed"
+    };
+  }
+}
+const C = (e, t) => f(["agentRegistry"], "Help Agent")(e, t);
+async function H(e, t) {
+  const r = new E(m);
+  try {
+    const s = e.helpInternalState.toolCallMessage;
+    if (!s)
+      throw new Error("helpToolCalling: missing helpInternalState.toolCallMessage");
+    const a = (await r.invoke({ messages: [s] }, t)).messages.map((o) => o.text).join(`
+`);
+    return await c({ text: `Finished executing help tool: ${a}` }, t), {
+      ...e,
+      outputMessage: a,
+      status: "success",
+      summary: a ? y(a) : "Help executed.",
+      helpInternalState: {
+        ...e.helpInternalState,
+        toolCallMessage: void 0
+      }
+    };
+  } catch (s) {
+    const l = s instanceof Error ? s.message : String(s);
+    return await c({ text: `Help tool execution failed: ${l}` }, t), {
+      ...e,
+      outputMessage: `Help tool execution failed: ${l}`,
+      status: "failed",
+      summary: `Help tool execution failed: ${l}`,
+      helpInternalState: {
+        ...e.helpInternalState,
+        toolCallMessage: void 0
+      }
+    };
+  }
+}
+const b = () => new d(u).addNode("requireHelpServices", C).addNode("agent", _).addNode("tools", H).addEdge(g, "requireHelpServices").addEdge("requireHelpServices", "agent").addConditionalEdges("agent", (t) => t.helpInternalState.toolCallMessage ? "tools" : i).addEdge("tools", i), M = String.raw`- **help** — Enables users to ask questions about the map, layers, fields, and it's capabilities.
+
+  _Example: “Tell me about this map”_  
+  _Example: “List all layers in this map”_  
+  _Example: “List fields in protected areas layer”_  
+  _Example: “What agents are available to me?”_  
+  _Example: “What can you do?”_  
+  _Example: “What can I ask”_
+  
+  Even if the user asks unrelated queries like "What are the vowels in English alphabet" or "How to cook", call this agent.
+  
+  IF the user asks map related queries, but those that are not performed by any of the agents, call this agent so we can respond accordingly.
+  _Example: "Create a chart"_
+  _Example: "Create a table"_`, D = {
+  id: "help",
+  name: "Help Agent",
+  description: M,
+  createGraph: b,
+  workspace: u
+};
+export {
+  D as H
+};

package/dist/chunks/help_prompt.js

@@ -0,0 +1,57 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+const e = `## Map Query Gate
+
+### Input
+
+Assigned task:
+{assignedTask}
+
+Latest user request:
+{userRequest}
+
+Prior steps:
+{priorSteps}
+
+Use the assigned task as the primary instruction for the current query. The question will **not** be restated again here.
+Use the latest user request as supporting context when needed.
+Use prior steps only when needed to explain a previous result, failure, or likely next action.
+
+### Map Context
+
+{layerSummary}
+
+## Available agents (capabilities)
+
+{agents}
+
+### Rules
+
+- "What layers are in this map?" → List the layer names
+- "What fields are in this layer?" → Call the tool to list the field names for that layer
+- "What can you do?" / "What can I ask?" → Suggest specific queries using EXACT layer and field names from the context above
+- "Tell me about this map" → Summarize layers and capabilities
+- "Create a chart of all wells ans their depth" → If a question is map related but not supported by available capabilities, say so. Add that support for this might be added in the future.
+- Questions completely unrelated to maps/GIS → Politely explain you only help with the map |
+
+### Response Guidelines
+
+When suggesting what users can ask, be SPECIFIC using actual layer names:
+
+- "Show me water sources with elevation above 500"
+- "Filter Protected Areas in Panama by protection level"
+- "Zoom to Watershed Boundaries"
+
+For "what can I ask" responses, provide 3-5 specific example queries using fields from the context.
+
+For off-topic questions:
+"I can only help with this map. Try asking me to filter [LayerName] by [FieldName], or zoom to a location."
+
+Rules:
+
+- Keep responses concise
+- Use bullet points for lists
+- Use new lines (\\n) and appropriate formatting in your response
+`;
+export {
+  e as default
+};

package/dist/chunks/intent_prompt.js

@@ -0,0 +1,124 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+const e = `## GIS Agent Orchestrator
+
+You are an orchestrator for an ArcGIS Maps SDK for JavaScript system.
+
+Your job is to decide the single best next agent to execute for the current step.
+
+---
+
+## Inputs
+
+You are given:
+
+- the latest user request
+- relevant chat history
+- the list of registered agents
+- optional prior steps from earlier agent executions
+
+---
+
+## Output
+
+Return either:
+
+- one decision with:
+  1. \`agentId\` — the next agent to execute
+  2. \`assignedTask\` — a clear, actionable task for that agent
+  3. \`requiresFollowUp\` — whether another orchestration step will likely be needed after this agent succeeds
+
+- or \`null\` if no registered agent applies
+
+---
+
+## Important
+
+- Return \`null\` only when the request is clearly outside the scope of all registered agents.
+- If any agent can take the next useful step, select the best one instead of returning \`null\`.
+
+---
+
+## Context
+
+### Latest user request
+
+{userRequest}
+
+### Registered agents
+
+Format:
+{{id: string, name: string, description: string}}[]
+
+{registeredAgents}
+
+### Prior steps
+
+Each step has:
+
+- \`agentId: string\`
+- \`assignedTask: string\`
+- \`summary: string\`
+- \`status: "success" | "failed" | "unknown"\`
+
+Use prior steps to:
+
+- Avoid repeating work that has already succeeded
+- Retry or adjust steps that failed when appropriate
+
+{priorSteps}
+
+---
+
+## Rules
+
+- Focus primarily on the latest user request.
+- Use relevant chat history only when the latest request clearly depends on earlier context; otherwise ignore it.
+- Use prior steps to determine what has already been attempted or completed.
+- Do not plan the full workflow up front. Only decide the next best step.
+- Prefer an agent that can directly complete the user’s request.
+- Only break the request into multiple steps when necessary.
+- When multiple agents could help, choose the best fit instead of returning \`null\`.
+- Base the choice on the registered agent descriptions, not on whether the user used exact matching keywords.
+- If no agent can fully complete the request, but one agent can take the next useful step, choose that agent.
+- Do NOT reuse constraints from prior steps unless the current user request explicitly requires them.
+- Each step must reflect the current user request exactly.
+
+---
+
+## Constraint Interpretation
+
+Interpret the user’s wording precisely:
+
+- Do not substitute one type of constraint for another (e.g., distance vs containment, range vs exact match, etc.)
+- If the user specifies a constraint, use it exactly
+- If the user does not specify a constraint, do not assume or infer one
+
+Do not reinterpret the request into a different form.
+
+---
+
+## Assigned Task Guidelines (IMPORTANT)
+
+- The \`assignedTask\` must match the user’s request exactly in meaning
+- Do not add, remove, or transform constraints
+- Do not substitute one type of constraint for another
+- If a constraint is not explicitly stated, do not assume one
+
+- Keep the task short, specific, and directly executable
+- Keep wording close to the user’s request with minimal transformation
+- Use only information explicitly present in the user request or provided context
+
+- The \`assignedTask\` may represent only part of the user’s request when multiple steps are necessary
+
+---
+
+## requiresFollowUp Guidelines
+
+- \`requiresFollowUp\` should indicate a likely next agent step, not uncertainty about the current request
+- Set \`requiresFollowUp\` to \`true\` only when another orchestration step will likely be needed after this agent succeeds
+- Set \`requiresFollowUp\` to \`false\` when a successful result from this agent would likely complete the user-visible task
+- Default to \`false\`
+`;
+export {
+  e as default
+};

package/dist/chunks/layerStylingGraph.js

@@ -0,0 +1,189 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { NodeInterrupt as L, StateGraph as w, START as E, END as m } from "@langchain/langgraph/web";
+import "@arcgis/core/identity/IdentityManager.js";
+import "@arcgis/core/portal/Portal.js";
+import { s as i, j as I } from "./generateLayerDescriptions.js";
+import "@langchain/core/messages";
+import "@langchain/openai";
+import "@arcgis/core/core/reactiveUtils.js";
+import "@arcgis/core/layers/FeatureLayer.js";
+import "@arcgis/core/request.js";
+import "@langchain/core/prompts";
+import { f as p, z as v, A as R, B as T, C as F, D as C, E as A, F as $, I as N, J as b, K as q, L as M, g as _, r as j, M as S } from "./adapter.js";
+import { h as k } from "./toolCallResponse.js";
+import { ToolNode as V } from "@langchain/langgraph/prebuilt";
+const h = 0.7, z = 10, D = async (t, e) => {
+  try {
+    await i({ text: "Similarity search to find fields" }, e);
+    const r = p(e, "fieldSearch"), a = p(e, "layersAndFieldsRegistry"), o = p(e, "embeddingCache"), n = await r.searchFields({
+      text: t.agentExecutionContext.assignedTask,
+      layerIds: t.vectorSearchLayerIds,
+      minScore: h,
+      topResults: z,
+      embeddingCache: o
+    }), c = n.map(({ layerId: d, results: g }) => {
+      const y = g.map((s) => `  - ${s.name} (${s.score.toFixed(2)})`).join(`
+`);
+      return `${a.get(d)?.layerItem.name ?? d}:
+${y}`;
+    }).join(`
+`);
+    let l;
+    return n.length > 0 ? l = `Vector search completed. Matching layers and fields with scores:
+${c}` : l = `No vector search results found for score over ${h}.`, await i({ text: l }, e), {
+      ...t,
+      vectorSearchFieldResults: n
+    };
+  } catch (r) {
+    throw await i(
+      { text: `Error during vector search: ${r instanceof Error ? r.message : String(r)}` },
+      e
+    ), new Error(`Vector search failed: ${r instanceof Error ? r.message : String(r)}`);
+  }
+}, P = 0.7, H = async (t, e) => {
+  try {
+    await i(
+      { text: `Similarity search to find layers: ${t.agentExecutionContext.assignedTask}` },
+      e
+    );
+    const r = p(e, "layerSearch"), a = p(e, "layersAndFieldsRegistry"), o = await r.searchLayers({
+      text: t.agentExecutionContext.assignedTask,
+      minScore: P
+    }), n = o.map((d) => d.id), c = o.map(({ id: d, score: g }) => `${a.get(d)?.layerItem.name ?? d} (${g.toFixed(2)})`).join(`
+`);
+    let l;
+    return n.length > 0 ? l = `Vector search completed. Matching layers with scores:
+${c}` : l = "Vector search completed. No matching layers found.", await i({ text: l }, e), {
+      ...t,
+      vectorSearchLayerIds: n
+    };
+  } catch (r) {
+    throw await i(
+      { text: `Error during vector search: ${r instanceof Error ? r.message : String(r)}` },
+      e
+    ), new Error(`Vector search failed: ${r instanceof Error ? r.message : String(r)}`);
+  }
+}, f = [
+  v,
+  R,
+  T,
+  F,
+  C,
+  A,
+  $,
+  N,
+  b,
+  q,
+  M
+], x = (t, e = 3) => {
+  const r = t.map((o, n) => o.type === "human" ? n : -1).filter((o) => o !== -1);
+  if (r.length === 0)
+    return [];
+  const a = r.length > e ? r[r.length - e] : r[0];
+  return t.slice(a);
+}, G = async (t, e) => {
+  await i({ text: "Requesting LLM for layer query results" }, e);
+  const r = await _("navigation_intent_prompt");
+  if (!e?.configurable)
+    throw new Error("config.configurable is required for layer query tools");
+  const a = {
+    layerFieldInfo: t.layerFieldInfo
+  }, o = await I({
+    promptText: r,
+    modelTier: "advanced",
+    messages: x(t.agentExecutionContext.messages),
+    inputVariables: a,
+    tools: f
+  });
+  return await k(o, e), {
+    ...t,
+    agentExecutionContext: {
+      ...t.agentExecutionContext,
+      messages: [...t.agentExecutionContext.messages, o]
+    }
+  };
+};
+async function B(t, e) {
+  const a = await new V(f).invoke(
+    {
+      messages: x(t.agentExecutionContext.messages)
+    },
+    e
+  ), o = a.messages.map((c) => c.text).join(`
+`);
+  await i({ text: `Finished executing layer filter tool: ${o}` }, e);
+  const n = a.messages.map((c) => c.text).join(`
+`);
+  return { ...t, outputMessage: n };
+}
+const U = async (t, e) => (await i({ text: "Exiting Layer Styling agent" }, e), t), J = async (t, e) => {
+  try {
+    await i({ text: "Populating layer and field info" }, e);
+    const r = [];
+    for (const a of t.vectorSearchFieldResults) {
+      let o = function(y) {
+        const s = l.get(y)?.layerItem;
+        return s ? [
+          s.name && `Name: ${s.name}`,
+          s.title && `Title: ${s.title}`,
+          s.description && `Description: ${s.description}`
+        ].filter(Boolean).join(" | ") : y;
+      };
+      const { layerId: n, results: c } = a, l = p(e, "layersAndFieldsRegistry"), d = l.get(n)?.fieldRegistry;
+      if (!d)
+        continue;
+      let g = r.find((y) => y.layerId === n);
+      g || (g = {
+        layerId: n,
+        layerSummary: o(n),
+        fieldInfos: []
+      }, r.push(g));
+      for (const y of c) {
+        const s = d.get(y.name);
+        s && g.fieldInfos.push(s);
+      }
+    }
+    return await i({ text: "Populated layerFieldInfo" }, e), { ...t, layerFieldInfo: r };
+  } catch (r) {
+    throw await i({ text: "Error populating layerFieldInfo" }, e), new Error(`Error populating layerFieldInfo: ${r instanceof Error ? r.message : String(r)}`);
+  }
+}, K = (t, e) => {
+  const r = t.vectorSearchLayerIds ?? [];
+  if (r.length <= 1)
+    return { ...t, selectedLayerId: t.vectorSearchLayerIds[0] };
+  const { hitlResponse: a } = e.configurable;
+  if (a?.agentId !== u.id || a.id !== "reviewLayerSelection") {
+    const n = {
+      agentId: u.id,
+      id: "reviewLayerSelection",
+      kind: "singleSelection",
+      message: "Choose a layer to apply the styles.",
+      metadata: [...r]
+    };
+    throw new L(n);
+  }
+  let o = null;
+  return Array.isArray(a.payload) && a.payload.length > 0 && (o = a.payload[0]), {
+    ...t,
+    selectedLayerId: o ?? t.vectorSearchLayerIds[0]
+  };
+}, O = (t, e) => j(["layerSearch", "fieldSearch", "layersAndFieldsRegistry"], "Layer Styling Agent")(t, e), Q = () => new w(S).addNode("requireLayerStylingServices", O).addNode("vectorSearchLayers", H).addNode("layerSelectionHITL", K).addNode("vectorSearchFields", D).addNode("populateLayerFieldInfo", J).addNode("agent", G).addNode("tools", B).addNode("earlyExit", U).addEdge(E, "requireLayerStylingServices").addEdge("requireLayerStylingServices", "vectorSearchLayers").addConditionalEdges(
+  "layerSelectionHITL",
+  (e) => e.vectorSearchLayerIds.length ? "vectorSearchFields" : "earlyExit"
+).addConditionalEdges(
+  "vectorSearchFields",
+  (e) => e.vectorSearchFieldResults.length ? "populateLayerFieldInfo" : "earlyExit"
+).addEdge("populateLayerFieldInfo", "agent").addEdge("agent", "tools").addEdge("tools", m).addEdge("earlyExit", m), W = String.raw`- **layerStyling** — User wants to change how features are drawn or styled on the map based on their data, such as applying color, size, transparency, symbols, or charts according to field values.
+  _Example: “Color points by sales amount”_
+  _Example: “Show population density with a color gradient”_
+  _Example: “Create a relationship map between height and depth”_
+  _Example: “Vary circle sizes according to population”_`, u = {
+  id: "layerStyling",
+  name: "Layer Styling Agent",
+  description: W,
+  createGraph: Q,
+  workspace: S
+};
+export {
+  u as L
+};

package/dist/chunks/layer_descriptions_prompt.js

@@ -0,0 +1,59 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+const e = `This Feature Layer is part of a Feature Service. The Feature Layer contains various fields, each with its own name, type, and description.
+The Feature Layer is a collection of geographic features that represent real-world entities. Each feature in the layer has attributes that provide additional information about the feature. The layer may include point, line, or polygon geometries, depending on the type of data it represents.
+The geometry type for this layer is {layerGeometryType}.
+
+Here is the field information for each field in the Feature Layer. Each field has a name, alias, type, valueType and description. These should help you understand the data represented in the Feature Layer.
+
+Field Descriptions:
+{fieldInformation}
+
+Your task is to :
+
+- analyze the field descriptions to understand the data represented in the Feature Layer.
+- Generate the following for the layer:
+  - a title: a concise title that accurately reflects the content and purpose of the feature service.
+  - a description: a detailed description of the feature layer
+
+Consider the following aspects in your description:
+
+- purpose of this feature layer
+- types of data and geometric entities represented in the layer
+- sources of the layer information and the geographic area covered
+- potential applications and usefulness of the feature layer in the GIS world
+
+If any of the above topics are not applicable, you can skip them. Don't include statements that indicate something this Feature Layer is not or does not have. Avoid listing field names, types, and other technical details.
+
+Instructions while generating the title:
+
+- Avoid using special characters in the title.
+- Avoid using 'layer' in the title.
+- Avoid using all uppercase letters in the title. Use title case instead.
+- The title should not be too long.
+
+You are given Feature Layer descriptions and title.
+
+## Existing layer details filled in by a human:
+
+{existingLayerTitle}
+{existingLayerSnippet}
+{existingLayerDescription}
+
+## Instructions on how to use the information filled in by a human:
+
+Remember humans may have more information about the item than just the field and layer descriptions.
+
+- Use this information ONLY IF it helps you understand the item better.
+- Use this information ONLY IF it helps you generate a better description and title.
+- Use your knowledge from this information to compensate for any important information that is missing in the field and layer descriptions.
+
+## Instructions on what to avoid doing with the information filled in by a human:
+
+- you must not use this information in your response as it is.
+- you must not think of this information as the final version.
+- you must not use this information to generate a response without analyzing it.
+- you must not copy this information verbatim in your response.
+`;
+export {
+  e as default
+};

package/dist/chunks/layer_styling_prompt.js

@@ -0,0 +1,72 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+const e = `# ArcGIS Online Map Viewer — Smart Mapping Assistant
+
+You are a Smart Mapping Assistant for ArcGIS Online Map Viewer.
+
+**Your job:**  
+Given a set of layers with their fields and a user request, call the appropriate layer styling tools to apply the best mapping style(s) for each layer.
+
+---
+
+## **Available Layers and Fields:**
+
+{layerFieldInfo}
+
+**FieldInfo:**
+
+- \`name\`: the actual field name (use this exact name)
+- \`type\`: one of \`string\`, \`number\`, \`date\`, etc.
+- \`alias\`: a human-readable label
+- \`description\`: optional field metadata
+
+---
+
+## **Available Color Schemes:**
+
+\`reds\`, \`yellows\`, \`oranges\`, \`greens\`, \`blues\`, \`purples\`, \`pinks\`, \`browns\`, \`grays\`, \`subdued\`, \`diverging\`, \`sequential\`, \`categorical\`
+
+---
+
+## **Available Themes:**
+
+1. **high-to-low** - High values are emphasized with saturated colors. Low values are de-emphasized with diminished colors.
+   - Keywords: continuous, high to low, unclassed, gradient, sequential
+   - Example: Show the percent of the population that owns a home along a sequential color ramp.
+
+2. **above** - Emphasize values that are above a value, such as the mean.
+   - Keywords: over, increasing, up, growth, above
+   - Example: Use color to show areas where the hispanic population is above the mean.
+
+3. **below** - Emphasize values that are below a value, such as the mean.
+   - Keywords: under, decreasing, down, shrinking, decline, drop, below
+   - Example: Show the number of vacant homes below the mean.
+
+4. **centered-on** - Emphasize values that are near a key value.
+   - Keywords: centered on, focused on average, highlight average, competitive, close
+   - Example: Use color to show the areas where the percent of the republican votes is close to the percent of democratic votes.
+
+5. **above-and-below** - When both high values and low values need emphasis.
+   - Keywords: diverging, above or below, bi-directional, over or under, growing or shrinking, growth or decline
+   - Example: Show the median household income above and below the national average.
+
+6. **extremes** - When only the highest or lowest values need emphasis.
+   - Keywords: extremes, outliers
+   - Example: Emphasize the outliers of the votes for Democrats in the 2020 presidential election.
+
+---
+
+## **Instructions:**
+
+- Call the appropriate tool for the layer based on the user's request
+- Use exact field names from the layer info (not aliases)
+- Use exact layer IDs from the layer info
+- Match field types to tool requirements (each tool describes its field requirements in its description)
+- Select appropriate color schemes and themes based on the data and user intent, only if user asks for them
+- If the user asks for a specific style, use that tool
+- If the user is vague, use your judgment to recommend the best tool
+
+**Remember:** Each layer styling tool will apply a renderer to a layer, make it visible, and return results.
+`;
+export {
+  e as default
+};