@arcgis/ai-components 5.2.0-next.12 → 5.2.0-next.120

package/dist/agents/tools/navigation/goToBookmark/adapter.js

@@ -0,0 +1,30 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { z as i } from "zod";
+import { tool as k } from "@langchain/core/tools";
+import { f as s } from "../../../../chunks/fetchAgentContext.js";
+async function c(o, t) {
+  const e = t.map.bookmarks;
+  if (!e || e.length === 0)
+    throw new Error("No bookmarks found in the map.");
+  const n = e.find((m) => m.name === o);
+  if (!n)
+    throw new Error(`Bookmark with name "${o}" not found.`);
+  const a = n.viewpoint;
+  if (!a)
+    throw new Error(`Bookmark with name "${o}" does not have a valid viewpoint.`);
+  return await t.goTo(a), { text: `Navigated to bookmark: ${o}` };
+}
+async function h({ bookmarkName: o }, t) {
+  const { mapView: r } = s(t, ["mapView"]);
+  return await Promise.resolve(c(o, r));
+}
+const w = i.object({
+  bookmarkName: i.string().describe("The name of the bookmark to navigate to.")
+}), b = k(h, {
+  name: "goToBookmark",
+  description: "Go to the extent of the bookmark with the given name.",
+  schema: w
+});
+export {
+  b as goToBookmarkTool
+};

package/dist/agents/tools/navigation/goToFeatures/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Navigates to features that match a layer and SQL where clause.
+ *
+ * @internal
+ */
+export const goToFeaturesTool: StructuredToolInterface;

package/dist/agents/tools/navigation/goToFeatures/adapter.js

@@ -0,0 +1,50 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { z as i } from "zod";
+import { tool as u } from "@langchain/core/tools";
+import { f as c } from "../../../../chunks/fetchAgentContext.js";
+async function f(o, a, n) {
+  const e = n.map?.allLayers.find((r) => r.id === o);
+  if (!e)
+    return { text: `Error: Layer with id ${o} not found` };
+  const t = a?.trim() ? a : "1=1", l = e.createQuery();
+  l.where = t;
+  try {
+    const { extent: r, count: s } = await e.queryExtent(l);
+    if (s === 0)
+      return { text: `No features found in ${e.title} matching: ${t}`, where: t };
+    if (r)
+      await n.goTo(r);
+    else
+      return { text: `Error: Unable to determine extent for ${e.title}`, where: t };
+    const d = {
+      layerId: o,
+      layerTitle: e.title ?? o,
+      where: t,
+      count: s
+    };
+    return {
+      text: `Successfully zoomed to ${s} feature(s) in ${e.title} matching: ${t}`,
+      where: t,
+      sharedStatePatch: { lastNavigatedFeatures: { value: d } }
+    };
+  } catch (r) {
+    return console.error("Error in goToFeatures:", r), { text: `Error: ${r instanceof Error ? r.message : "Unknown error"}`, where: t };
+  }
+}
+async function h({ layerId: o, where: a }, n) {
+  const { mapView: e } = c(n, ["mapView"]);
+  return await f(o, a, e);
+}
+const m = i.object({
+  layerId: i.string().describe("The layerId of the layer to zoom to."),
+  where: i.string().describe(
+    "ArcGIS SQL-92 WHERE expression used for `query.where` on the selected layer. Start with a fresh filter for the current request unless the task explicitly refers to prior results. Use only field name values from the selected layer, not aliases. Use field metadata only to interpret intent: prefer LIKE '%value%' for string fields, and use =, <, >, BETWEEN, IN, IS NULL, AND/OR/NOT as appropriate for number/date fields. For coded-value domain fields, use the domain code already provided in layerInfo.domain.codedValues, never the display label. Respect range-domain bounds when they are provided. Do NOT include subqueries, nested SELECT, JOIN, GROUP BY, HAVING, ORDER BY, or semicolons."
+  )
+}), E = u(h, {
+  name: "goToFeatures",
+  description: "Go to the features that match the given filter for the given layerId. Use coded-value domain codes from layer field metadata when building the WHERE clause.",
+  schema: m
+});
+export {
+  E as goToFeaturesTool
+};

package/dist/agents/tools/navigation/goToFullExtent/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Navigates the map to the full world extent.
+ *
+ * @internal
+ */
+export const goToFullExtentTool: StructuredToolInterface;

package/dist/agents/tools/navigation/goToFullExtent/adapter.js

@@ -0,0 +1,27 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { z as n } from "zod";
+import r from "@arcgis/core/geometry/Extent.js";
+import { tool as i } from "@langchain/core/tools";
+import { f as l } from "../../../../chunks/fetchAgentContext.js";
+async function m(o) {
+  const t = new r({
+    xmin: -180,
+    ymin: -90,
+    xmax: 180,
+    ymax: 90,
+    spatialReference: { wkid: 4326 }
+  }).expand(0.7);
+  return await o.goTo(t), { text: "Successfully zoomed to world extent" };
+}
+async function a(o, e) {
+  const { mapView: t } = l(e, ["mapView"]);
+  return await m(t);
+}
+const c = n.object({}), f = i(a, {
+  name: "goToFullExtent",
+  description: "Zooms the map to the full world extent using Esri's Geocoding Service.",
+  schema: c
+});
+export {
+  f as goToFullExtentTool
+};

package/dist/agents/tools/navigation/goToHomeExtent/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Returns the map to its initial viewpoint.
+ *
+ * @internal
+ */
+export const goToHomeExtentTool: StructuredToolInterface;

package/dist/agents/tools/navigation/goToHomeExtent/adapter.js

@@ -0,0 +1,24 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as n } from "@langchain/core/tools";
+import i from "zod";
+import { f as r } from "../../../../chunks/fetchAgentContext.js";
+async function a(e) {
+  const t = e.map.initialViewProperties?.viewpoint?.targetGeometry;
+  if (t)
+    await e.goTo(t);
+  else
+    throw new Error("Initial extent is undefined");
+  return { text: "Successfully zoomed to home extent" };
+}
+async function m(e, o) {
+  const { mapView: t } = r(o, ["mapView"]);
+  return await a(t);
+}
+const c = i.object({}), w = n(m, {
+  name: "goToHomeExtent",
+  description: "Go to the initial web map view extent",
+  schema: c
+});
+export {
+  w as goToHomeExtentTool
+};

package/dist/agents/tools/navigation/goToLayer/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Navigates to the full extent of a layer.
+ *
+ * @internal
+ */
+export const goToLayerTool: StructuredToolInterface;

package/dist/agents/tools/navigation/goToLayer/adapter.js

@@ -0,0 +1,26 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { z as r } from "zod";
+import { tool as i } from "@langchain/core/tools";
+import { f as c } from "../../../../chunks/fetchAgentContext.js";
+async function l(o, t) {
+  await t.when();
+  const e = t.map?.allLayers.find((n) => n.id === o);
+  if (!e)
+    return console.warn(`[goToLayer] No matching FeatureLayer found for: ${o}`), { text: `Could not find layer for: ${o}` };
+  let a;
+  return (e.type === "link-chart" || e.type === "knowledge-graph-sublayer") && t.map?.activeLinkChartLayer ? a = t.map.diagramNodesExtent : a = e.fullExtent, a ? (await t.goTo(a), e.visible = !0, { text: `Successfully zoomed to: ${e.title ?? ""}` }) : { text: "Layer has no defined extent. Cannot zoom to layer." };
+}
+async function f({ layerId: o }, t) {
+  const { mapView: e } = c(t, ["mapView"]);
+  return await l(o, e);
+}
+const s = r.object({
+  layerId: r.string().describe("The id of the layer to navigate to")
+}), h = i(f, {
+  name: "goToLayer",
+  description: "Zooms the map view to the full extent of the top matching layer.",
+  schema: s
+});
+export {
+  h as goToLayerTool
+};

package/dist/agents/tools/navigation/goToScale/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Navigates the map to a specified scale.
+ *
+ * @internal
+ */
+export const goToScaleTool: StructuredToolInterface;

package/dist/agents/tools/navigation/goToScale/adapter.js

@@ -0,0 +1,21 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import t from "zod";
+import { tool as a } from "@langchain/core/tools";
+import { f as i } from "../../../../chunks/fetchAgentContext.js";
+async function n(o, e) {
+  return await e.goTo({ scale: o }), { text: `Successfully zoomed to: ${o}` };
+}
+async function r({ scale: o }, e) {
+  const { mapView: c } = i(e, ["mapView"]);
+  return await n(o, c);
+}
+const m = t.object({
+  scale: t.number().describe("The map scale of the view to go to.")
+}), f = a(r, {
+  name: "goToScale",
+  description: "Go to the specified view scale.",
+  schema: m
+});
+export {
+  f as goToScaleTool
+};

package/dist/agents/tools/navigation/goToViewpoint/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Navigates to a center point with optional zoom and scale values.
+ *
+ * @internal
+ */
+export const goToViewpointTool: StructuredToolInterface;

package/dist/agents/tools/navigation/goToViewpoint/adapter.js

@@ -0,0 +1,42 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import t from "zod";
+import { tool as c } from "@langchain/core/tools";
+import l from "@arcgis/core/geometry/Point.js";
+import { f as r } from "../../../../chunks/fetchAgentContext.js";
+async function m(e, a, o) {
+  const i = {
+    target: new l({
+      longitude: e.longitude,
+      latitude: e.latitude,
+      spatialReference: { wkid: 4326 }
+    })
+  };
+  return o?.zoom !== void 0 && (i.zoom = o.zoom), o?.scale !== void 0 && (i.scale = o.scale), await a.goTo(i), { text: `Successfully navigated to: ${[
+    `(${e.latitude}°, ${e.longitude}°)`,
+    o?.zoom !== void 0 ? `zoom ${o.zoom}` : "",
+    o?.scale !== void 0 ? `scale 1:${o.scale}` : ""
+  ].filter(Boolean).join(", ")}` };
+}
+async function d({
+  center: e,
+  zoom: a,
+  scale: o
+}, n) {
+  const { mapView: i } = r(n, ["mapView"]);
+  return await m(e, i, { zoom: a, scale: o });
+}
+const s = t.object({
+  center: t.object({
+    longitude: t.number().describe("The longitude (x-coordinate) of the point to navigate to."),
+    latitude: t.number().describe("The latitude (y-coordinate) of the point to navigate to.")
+  }),
+  zoom: t.number().optional().describe("The zoom level. Higher values = more zoomed in."),
+  scale: t.number().optional().describe("The map scale. Alternative to zoom. Smaller numbers = more zoomed in.")
+}), T = c(d, {
+  name: "goToViewpoint",
+  description: "Go to the specified viewpoint. This can contain a combination of scale, center, zoom, etc.",
+  schema: s
+});
+export {
+  T as goToViewpointTool
+};

package/dist/agents/tools/navigation/goToZoom/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Navigates the map to a specified zoom level.
+ *
+ * @internal
+ */
+export const goToZoomTool: StructuredToolInterface;

package/dist/agents/tools/navigation/goToZoom/adapter.js

@@ -0,0 +1,21 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import t from "zod";
+import { tool as m } from "@langchain/core/tools";
+import { f as i } from "../../../../chunks/fetchAgentContext.js";
+async function r(o, e) {
+  return await e.goTo({ zoom: o }), { text: `Successfully zoomed to: ${o}` };
+}
+async function a({ zoom: o }, e) {
+  const { mapView: n } = i(e, ["mapView"]);
+  return await r(o, n);
+}
+const c = t.object({
+  zoom: t.number().min(1).max(20).describe("The zoom level of the view to go to.")
+}), l = m(a, {
+  name: "goToZoom",
+  description: 'Go to the specified zoom level. If input is generic (e.g. "zoom in", then only zoom to the next appropriate level - increase level for zooming in and decrease for zooming out.).',
+  schema: c
+});
+export {
+  l as goToZoomTool
+};

package/dist/agents/tools/query/getAttribute/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Returns a formatted field value from the first feature matching a query.
+ *
+ * @internal
+ */
+export const getAttributeTool: StructuredToolInterface;

package/dist/agents/tools/query/getAttribute/adapter.js

@@ -0,0 +1,40 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as f } from "@langchain/core/tools";
+import i from "zod";
+import { f as h, g } from "../../../../chunks/formatFeatureAttributes.js";
+import { f as y } from "../../../../chunks/fetchAgentContext.js";
+const b = (a, e, o) => {
+  const t = a.createQuery();
+  return t.outFields = [e], t.where = o || "1=1", t.num = 1, t;
+}, d = async (a, e, o, t) => {
+  const r = t.map?.allLayers.find((m) => m.id === a), n = b(r, e, o.where), u = (await r.queryFeatures(n)).features[0], c = u ? u.attributes[e] : null, l = h(r, e, c, t.timeZone), s = g(r, e);
+  return {
+    tool: "getAttribute",
+    layerName: r.title ?? a,
+    summary: `${s} = ${l}`,
+    details: {
+      fieldName: e,
+      fieldAlias: s !== e ? s : void 0,
+      value: l,
+      where: o.where
+    }
+  };
+};
+async function p({ layerId: a, fieldName: e, query: o }, t) {
+  const { mapView: r } = y(t, ["mapView"]), n = await d(a, e, o, r);
+  return JSON.stringify(n, null, 2);
+}
+const w = i.object({
+  layerId: i.string().describe("The layerId of the layer containing the field from which to get a value."),
+  fieldName: i.string().describe("The name of the field/attribute from which to get a field value."),
+  query: i.object({
+    where: i.string().describe("The SQL-92 where clause representing the feature from which to get an attribute value.")
+  })
+}), Q = f(p, {
+  name: "getAttribute",
+  description: "Returns an attribute value for a given feature.",
+  schema: w
+});
+export {
+  Q as getAttributeTool
+};

package/dist/agents/tools/query/getStatistics/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Calculates an aggregate statistic for a field with optional spatial filtering.
+ *
+ * @internal
+ */
+export const getStatisticsTool: StructuredToolInterface;

package/dist/agents/tools/query/getStatistics/adapter.js

@@ -0,0 +1,158 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { tool as L } from "@langchain/core/tools";
+import t from "zod";
+import E from "@arcgis/core/smartMapping/statistics/summaryStatistics.js";
+import R from "@arcgis/core/smartMapping/statistics/uniqueValues.js";
+import V from "@arcgis/core/layers/support/FeatureFilter.js";
+import { c as x, m as v } from "../../../../chunks/mergeWhereClauses.js";
+import { g as O, i as S, a as C, s as N, r as G } from "../../../../chunks/resolveGeometryFilter.js";
+import { f as U } from "../../../../chunks/fetchAgentContext.js";
+import { f as W } from "../../../../chunks/fetchService.js";
+import { distanceUnitsSchema as I } from "../../shared/types.js";
+const j = async (h) => {
+  const { targetLayer: a, fieldName: n, statisticType: l, mapView: i, layersAndFieldsRegistry: p, geometryFilter: e } = h, s = i.map?.allLayers.find((r) => r.id === a.layerId);
+  if (!s)
+    throw new Error(`Layer '${a.layerId}' not found.`);
+  const w = await i.whenLayerView(s), o = p.get(a.layerId)?.fieldRegistry.get(n), F = o?.alias;
+  if (!o)
+    throw new Error(`Field '${n}' not found.`);
+  let b, u;
+  if (e) {
+    const r = await O(e, i);
+    if ("error" in r)
+      throw new Error(r.error);
+    if (!r.geometry)
+      throw S(e) ? new Error(`No features found matching: ${e.where}`) : new Error("Failed to create geometry");
+    if (S(e)) {
+      const g = i.map?.allLayers.find((f) => f.id === e.layerId);
+      b = {
+        geometryLayerName: g?.title ?? g?.id,
+        geometryLayerId: e.layerId,
+        geometryWhere: e.where,
+        distance: e.distance,
+        units: e.units,
+        applied: !0
+      };
+    } else C(e) && (b = {
+      point: e.point,
+      distance: e.distance,
+      units: e.units,
+      applied: !0
+    });
+    u = new V({
+      geometry: r.geometry,
+      distance: e.distance,
+      units: e.units,
+      spatialRelationship: "intersects"
+    });
+  }
+  const y = x(w, [n], !1);
+  let d = null, m = null;
+  const T = 10;
+  if (o.type !== "geometry" && o.type !== "oid" && o.type !== "global-id")
+    try {
+      const r = {
+        layer: s,
+        useFeaturesInView: y,
+        view: y ? i : void 0,
+        field: n,
+        sqlWhere: v(s.definitionExpression, a.where),
+        ...u && { filter: u },
+        outStatisticTypes: { include: [l] }
+      };
+      d = await E(r);
+      const g = ["string", "small-integer", "integer"], f = o.domain?.type === "coded-value" ? o.domain : null;
+      (g.includes(o.type) || f) && (m = (await R({
+        layer: s,
+        useFeaturesInView: y,
+        view: y ? i : void 0,
+        field: n,
+        sqlWhere: v(s.definitionExpression, a.where),
+        ...u && { filter: u }
+      })).uniqueValueInfos.sort((c, q) => q.count - c.count).slice(0, T)), m && o.domain?.type === "coded-value" && (m = m.map((c) => ({
+        ...c,
+        value: f ? f.getName(c.value) ?? c.value : c.value
+      })));
+    } catch (r) {
+      console.error("Statistics error:", r);
+    }
+  return {
+    tool: "getStatistics",
+    layerName: s.title ?? a.layerId,
+    summary: `${l} = ${typeof d?.[l] == "number" ? d[l] : "N/A"}`,
+    details: {
+      fieldName: n,
+      fieldAlias: F,
+      statisticType: l,
+      statistic: d?.[l] ?? null,
+      summaryStatistics: d,
+      uniqueValues: m,
+      where: a.where,
+      spatialFilterInfo: b
+    }
+  };
+};
+async function A({
+  targetLayer: h,
+  fieldName: a,
+  statisticType: n,
+  geometryFilter: l
+}, i) {
+  const p = W(i, "layersAndFieldsRegistry"), { mapView: e } = U(i, ["mapView"]), s = G(
+    l,
+    i.state?.agentExecutionContext?.sharedResources
+  ), w = await j({
+    targetLayer: h,
+    fieldName: a,
+    statisticType: n,
+    mapView: e,
+    layersAndFieldsRegistry: p,
+    geometryFilter: s
+  });
+  return JSON.stringify(w, null, 2);
+}
+const D = t.object({
+  layerId: t.string().describe("The layerId of the layer containing the geometry by which to filter."),
+  where: t.string().describe("The SQL-92 where clause representing the features from which to filter."),
+  distance: t.number().optional().describe("The buffer distance around the geometry."),
+  units: I.optional().describe("The units for the distance buffer.")
+}), $ = t.object({
+  point: t.object({
+    x: t.number().describe("X coordinate (longitude) from navigation result"),
+    y: t.number().describe("Y coordinate (latitude) from navigation result"),
+    spatialReference: t.object({
+      wkid: t.number().describe("Spatial reference WKID (e.g., 4326 for WGS84)")
+    }).optional().describe("Spatial reference. Defaults to map's spatial reference if not provided.")
+  }).describe("Point coordinates from a previous navigation/geocoding result"),
+  distance: t.number().optional().describe("Optional buffer distance around the point."),
+  units: I.optional().describe("The units for the distance buffer.")
+}), P = t.object({
+  targetLayer: t.object({
+    layerId: t.string().describe("The layerId of the layer containing the field from which to get a value."),
+    where: t.string().describe("The SQL-92 where clause representing the feature from which to get an attribute value.")
+  }),
+  geometryFilter: t.union([D, $, N]).optional().describe(
+    "Geometry filter for spatial queries. Use 'sharedResourceId' with an ID from listSharedResources for a previously geocoded location. Use 'point' for inline coordinates or 'layerId/where' for features from another layer."
+  ),
+  fieldName: t.string().describe("The name of the field for which to get statistics. STRICTLY DO NOT use OBJECTID. Use any other field"),
+  statisticType: t.enum(["avg", "max", "median", "min", "stddev", "sum", "variance", "nullcount", "count"]).describe("The statistic type to calculate.")
+}), ee = L(A, {
+  name: "getStatistics",
+  description: `Computes a single aggregate statistic (max, min, avg, sum, median, stddev, variance) for a numeric field across matching features. Also returns frequency analysis for categorical fields.
+
+USE THIS TOOL FOR:
+- "What is the average/maximum/minimum/total [field]?" — aggregate computations
+- "Most common/frequent value of [field]?" — frequency analysis
+- Questions requiring a mathematical aggregation across many features
+
+DO NOT USE FOR:
+- "How many features match X?" — use queryFeatures instead (it returns totalCount)
+- "Show / list / find features" — use queryFeatures instead
+- Simple counts of features matching a condition — use queryFeatures instead
+
+Only call this tool when the answer requires computing an aggregate (avg, max, min, sum, median, stddev) over a field's values, not just counting or listing features.`,
+  schema: P
+});
+export {
+  ee as getStatisticsTool
+};

package/dist/agents/tools/query/getTopFeatures/adapter.d.ts

@@ -0,0 +1,8 @@
+import type { StructuredToolInterface } from "@langchain/core/tools";
+
+/**
+ * Returns top-ranked features based on grouping and ordering criteria.
+ *
+ * @internal
+ */
+export const getTopFeaturesTool: StructuredToolInterface;